Добавляете ли вы функцию потерь, улучшаете тестовое покрытие или пишете 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. Затем:
Создайте форк репозитория, над которым планируете работать. Перейдите на страницу репозитория проекта и нажмите кнопку «Вилка» . Это создаст копию репо под вашим именем пользователя. (Подробнее о том, как разветвить репозиторий, смотрите в этом руководстве .)
Клонируйте репозиторий в свою локальную систему.
$ git clone git@github.com:your-user-name/project-name.git
Создайте новую ветку для хранения вашей работы.
$ git checkout -b new-branch-name
Работайте над новым кодом. Пишите и запускайте тесты.
Зафиксируйте изменения.
$ git add -A
$ git commit -m "commit message here"
Отправьте изменения в репозиторий GitHub.
$ git push origin branch-name
Откройте запрос на включение (PR). Перейдите к исходному репозиторию проекта на GitHub. Появится сообщение о вашей недавно отправленной ветке с вопросом, хотите ли вы открыть запрос на включение. Следуйте подсказкам, сравните данные из разных репозиториев и отправьте PR. Это отправит электронное письмо коммиттерам. Возможно, вы захотите отправить электронное письмо в список рассылки для большей видимости. (Подробнее см. в руководстве GitHub по PR .
Специалисты по сопровождению и другие участники проверят ваш PR . Пожалуйста, примите участие в обсуждении и попытайтесь внести любые запрошенные изменения . После утверждения PR код будет объединен.
Прежде чем приступить к работе над следующим вкладом , убедитесь, что ваш локальный репозиторий обновлен.
Установите вышестоящий пульт дистанционного управления. (Вам нужно делать это только один раз для каждого проекта, а не каждый раз.)
$ git remote add upstream git@github.com:tensorflow/project-repo-name
Переключитесь на локальную ветку master.
$ git checkout master
Извлеките изменения из восходящего потока.
$ git pull upstream master
Отправьте изменения в свою учетную запись GitHub. (Необязательно, но это хорошая практика.)
$ git push origin master
Создайте новую ветку, если начинаете новую работу.
$ git checkout -b branch-name
Дополнительные ресурсы git
и GitHub:
Контрольный список для участников
- Прочтите правила участия .
- Прочтите Кодекс поведения .
- Убедитесь, что вы подписали Лицензионное соглашение для участников (CLA) .
- Проверьте, соответствуют ли ваши изменения рекомендациям .
- Проверьте, соответствуют ли ваши изменения стилю кодирования TensorFlow .
- Запустите модульные тесты .