Если вы добавляете функцию потерь, улучшаете тестовое покрытие или пишете 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. Потом:
Разветвите репо, над которым вы планируете работать. Перейдите на страницу репозитория проекта и нажмите кнопку Fork . Это создаст копию репо под вашим именем пользователя. (Подробнее о том, как разветвить репозиторий, см. в этом руководстве .)
Клонируйте репозиторий в свою локальную систему.
$ 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 .
- Запустите модульные тесты .