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

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

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

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

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

Вопросы для новых участников

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

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

Проверка кода

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

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

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

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

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

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

  • Насколько эффективен этот код? Можно ли его легко переписать для повышения эффективности?

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

  • Приведёт ли новый код к появлению новых зависимостей от других библиотек?

Тестирование и улучшение тестового покрытия.

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

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

Подробную информацию о процедурах тестирования в каждом проекте 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. Создайте запрос на слияние (Pull Request , PR). Перейдите в репозиторий исходного проекта на GitHub. Там будет сообщение о вашей недавно добавленной ветке с вопросом, хотите ли вы создать запрос на слияние. Следуйте подсказкам, сравните изменения в разных репозиториях и отправьте запрос на слияние. Это отправит электронное письмо разработчикам. Возможно, вам стоит отправить письмо в список рассылки для большей видимости. (Более подробную информацию см. в руководстве GitHub по запросам на слияние .)

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

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

  1. Настройте удаленный источник данных. (Это нужно сделать только один раз для каждого проекта, а не каждый раз.)

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

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

    $ git checkout master

  3. Загрузите изменения из исходного кода.

    $ git pull upstream master

  4. Отправьте изменения в свой аккаунт GitHub. (Необязательно, но рекомендуется.)

    $ git push origin master

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

    $ git checkout -b branch-name

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

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