Внесите свой вклад в код 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. Создайте форк репозитория, над которым планируете работать. Перейдите на страницу репозитория проекта и нажмите кнопку «Вилка» . Это создаст копию репо под вашим именем пользователя. (Подробнее о том, как разветвить репозиторий, смотрите в этом руководстве .)

  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:

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