Внесите свой вклад в код TensorFlow

Если вы добавляете функцию потерь, улучшаете тестовое покрытие или пишете RFC для серьезного изменения дизайна, эта часть руководства для участников поможет вам начать работу. Спасибо за работу и интерес к улучшению TensorFlow.

Прежде чем начать

Прежде чем добавлять исходный код в проект TensorFlow, просмотрите файл CONTRIBUTING.md в репозитории проекта на GitHub. Например, см. файл CONTRIBUTING.md в основном репозитории TensorFlow. Все участники кода должны подписать лицензионное соглашение с участниками (CLA).

Чтобы избежать дублирования работы, просмотрите текущие или предлагаемые RFC и свяжитесь с разработчиками на форумах TensorFlow ( developers@tensorflow.org ), прежде чем начинать работу над нетривиальной функцией. Мы несколько избирательны при принятии решения о добавлении новых функций, и лучший способ внести свой вклад и помочь проекту — это работать над известными проблемами.

Проблемы для новых участников

Новые участники должны искать следующие теги при поиске первого вклада в кодовую базу TensorFlow. Мы настоятельно рекомендуем, чтобы новые участники сначала занимались проектами «хороший первый выпуск» и «вклады приветствуются»; это помогает участнику ознакомиться с рабочим процессом вклада, а основным разработчикам — познакомиться с участником.

Если вы заинтересованы в наборе команды для решения крупномасштабной проблемы или новой функции, отправьте электронное письмо в группу разработчиков @ и просмотрите наш текущий список RFC.

Обзор кода

Новые функции, исправления ошибок и любые другие изменения в кодовой базе подлежат проверке кода.

Проверка кода, внесенного в проект, поскольку запросы на вытягивание являются важным компонентом разработки TensorFlow. Мы призываем всех начать просматривать код, представленный другими разработчиками, особенно если вы, вероятно, будете использовать эту функцию.

Вот несколько вопросов, о которых следует помнить в процессе проверки кода:

  • Хотим ли мы этого в TensorFlow? Вероятно ли его использование? Нравится ли вам, как пользователю TensorFlow, изменение, и вы собираетесь его использовать? Является ли это изменением области применения TensorFlow? Будет ли стоимость поддержки новой функции стоить ее преимуществ?
  • Соответствует ли код API TensorFlow? Являются ли общедоступные функции, классы и параметры хорошо названными и интуитивно понятными?
  • Включает ли он документацию? Все ли общедоступные функции, классы, параметры, возвращаемые типы и хранимые атрибуты названы в соответствии с соглашениями TensorFlow и четко задокументированы? Описаны ли новые функции в документации TensorFlow и проиллюстрированы ли они примерами, когда это возможно? Правильно ли отображается документация?

  • Является ли код понятным для человека? Это низкая избыточность? Следует ли улучшить имена переменных для ясности или согласованности? Нужно ли добавлять комментарии? Следует ли удалять какие-либо комментарии как бесполезные или посторонние?

  • Эффективен ли код? Можно ли его легко переписать, чтобы он работал более эффективно?

  • Является ли код обратно совместимым с предыдущими версиями TensorFlow?

  • Будет ли новый код добавлять новые зависимости от других библиотек?

Тестируйте и улучшайте тестовое покрытие

Высококачественное модульное тестирование является краеугольным камнем процесса разработки TensorFlow. Для этого мы используем образы Docker. Тестовые функции названы соответствующим образом и отвечают за проверку правильности алгоритмов, а также различных вариантов кода.

Все новые функции и исправления ошибок должны включать адекватное тестовое покрытие. Мы также приветствуем вклад новых тестовых примеров или улучшений существующих тестов. Если вы обнаружите, что наши существующие тесты не завершены — даже если в настоящее время это не вызывает ошибки — сообщите о проблеме и, если возможно, запросе на включение.

Подробные сведения о процедурах тестирования в каждом проекте TensorFlow см. в README.md и CONTRIBUTING.md в репозитории проекта на GitHub.

Особые опасения при адекватном тестировании :

  • Проверяются ли все публичные функции и классы ?
  • Проверяется ли разумный набор параметров , их значений, типов значений и комбинаций?
  • Подтверждают ли тесты правильность кода и то, что он делает то, для чего, согласно документации, код предназначен?
  • Если изменение является исправлением ошибки, включен ли нерегрессионный тест ?
  • Проходят ли тесты сборку непрерывной интеграции ?
  • Охватывают ли тесты каждую строку кода? Если нет, то являются ли исключения разумными и явными?

Если вы обнаружите какие-либо проблемы, рассмотрите возможность помочь участнику понять эти проблемы и решить их.

Улучшить сообщения об ошибках или журналы

Мы приветствуем вклады, которые улучшают сообщения об ошибках и ведение журнала.

Рабочий процесс вклада

Добавление кода — исправление ошибок, новая разработка, улучшение тестирования — все это следует рабочему процессу, ориентированному на GitHub. Чтобы участвовать в разработке TensorFlow, создайте учетную запись GitHub. Потом:

  1. Разветвите репо, над которым вы планируете работать. Перейдите на страницу репозитория проекта и нажмите кнопку Fork . Это создаст копию репо под вашим именем пользователя. (Подробнее о том, как разветвить репозиторий, см. в этом руководстве .)

  2. Клонируйте репозиторий в свою локальную систему.

    $ git clone git@github.com:your-user-name/project-name.git

  3. Создайте новую ветку для хранения своей работы.

    $ git checkout -b new-branch-name

  4. Работайте над своим новым кодом. Пишите и запускайте тесты.

  5. Зафиксируйте свои изменения.

    $ git add -A

    $ git commit -m "commit message here"

  6. Отправьте свои изменения в репозиторий GitHub.

    $ git push origin branch-name

  7. Откройте запрос на слияние (PR). Перейдите к исходному репозиторию проекта на GitHub. Появится сообщение о вашей недавно отправленной ветке с вопросом, хотите ли вы открыть запрос на извлечение. Следуйте инструкциям, сравните репозитории и отправьте PR. Это отправит электронное письмо коммиттерам. Вы можете рассмотреть возможность отправки электронного письма в список рассылки для большей наглядности. (Подробнее см. в руководстве GitHub по PR .

  8. Сопровождающие и другие участники рассмотрят ваш PR . Пожалуйста, примите участие в обсуждении и попытайтесь внести необходимые изменения . После утверждения PR код будет объединен.

Прежде чем приступить к следующему вкладу , убедитесь, что ваш локальный репозиторий обновлен.

  1. Установите восходящий пульт. (Вам нужно сделать это только один раз для каждого проекта, а не каждый раз.)

    $ git remote add upstream git@github.com:tensorflow/project-repo-name

  2. Переключитесь на локальную ветку master.

    $ git checkout master

  3. Вытащите изменения из восходящего потока.

    $ git pull upstream master

  4. Отправьте изменения в свою учетную запись GitHub. (Необязательно, но это хорошая практика.)

    $ git push origin master

  5. Создайте новую ветку, если вы начинаете новую работу.

    $ git checkout -b branch-name

Дополнительные ресурсы git и GitHub:

Контрольный список участников