Google is committed to advancing racial equity for Black communities. See how.

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

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

Прежде, чем вы начнете

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

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

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

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

Если вы заинтересованы в наборе команды для решения крупномасштабной проблемы или создания новой функции, отправьте электронное письмо в группу разработчиков developers @ и просмотрите наш текущий список 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. Переключитесь на локальную главную ветку.

    $ git checkout master

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

    $ git pull upstream master

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

    $ git push origin master

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

    $ git checkout -b branch-name

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

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