Вклад в Docker

IRC — прямая линия к нашим самым осведомлённым пользователям Docker; у нас есть группы #docker и #docker-dev на irc.freenode.net. IRC — это богатый протокол чата, но он может... **Конвенции**

Форкните репозиторий и внесите изменения в своей ветке:

• Если это ветка исправления ошибок, назовите её XXXX-что-то, где XXXX — номер проблемы.
• Если это функциональная ветка, создайте заявку на улучшение, чтобы объявить о своих намерениях, и назовите её XXXX-что-то, где XXXX — номер проблемы.

Предоставьте модульные тесты для ваших изменений. Go имеет отличную встроенную тестовую среду; используйте её! Посмотрите на существующие тесты для вдохновения. Перед отправкой запроса на включение запустите полный набор тестов.

Обновляйте документацию при создании или изменении функций. Проверьте свои изменения документации на ясность, лаконичность и правильность, а также на чистоту сборки документации. Смотрите наше руководство для участников для ознакомления с руководством по стилю и инструкциями по сборке документации.

Пишите чистый код. Универсально отформатированный код способствует простоте написания, чтения и обслуживания. Всегда запускайте gofmt -s -w file.go для каждого изменённого файла перед фиксацией изменений. Большинство редакторов имеют плагины, которые делают это автоматически.

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

Сообщения фиксации должны начинаться с заглавной буквы и краткого резюме (максимум 50 символов), написанного в повелительном наклонении, за которым следует необязательный более подробный пояснительный текст, отделённый от резюме пустой строкой.

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

Запросы на включение должны быть аккуратно перебазированы поверх основной ветки без смешивания нескольких веток в PR.

Совет по Git: если ваш PR больше не объединяется чисто, используйте rebase master в своей функциональной ветке, чтобы обновить свой запрос на включение, вместо merge master.

Прежде чем делать запрос на включение, объедините свои фиксации в логические единицы работы с помощью git rebase -i и git push -f. Логическая единица работы — это согласованный набор исправлений, которые должны рассматриваться вместе: например, обновление версии сторонней зависимости и использование её теперь доступной новой функции составляют две отдельные единицы работы. Реализация новой функции и вызов её в другом файле составляют одну логическую единицу работы. Подавляющее большинство... Подчинения должны иметь один коммит, поэтому если есть сомнения: объедините их в один.

После каждого коммита убедитесь, что тестовый набор проходит успешно (https://docs.docker.com/opensource/project/test-and-docs/). Включайте изменения документации в тот же запрос на вытягивание, чтобы при отмене изменений были удалены все следы функции или исправления.

Включайте ссылки на проблемы, такие как «Закрывает #XXXX» или «Исправлено #XXXX», в коммиты, которые закрывают проблему. Включение ссылок автоматически закрывает проблему при слиянии.

Пожалуйста, не добавляйте себя в файл AUTHORS, так как он регулярно восстанавливается из истории Git.

См. раздел Стиль кодирования для получения дополнительных рекомендаций.

Утверждение слияния

Сопровождающие Docker используют LGTM (Looks Good To Me) в комментариях к проверке кода, чтобы указать на принятие.

Изменение требует LGTMs от абсолютного большинства сопровождающих каждого затронутого компонента. Например, если изменение затрагивает docs/ и registry/, оно требует абсолютного большинства от сопровождающих docs/ И отдельно — абсолютного большинства сопровождающих registry/.

Подробнее см. страницу MAINTAINERS.

Подпишите свою работу

Подпись представляет собой простую строку в конце объяснения патча. Ваша подпись подтверждает, что вы написали патч или иным образом имеете право передать его как патч с открытым исходным кодом. Правила довольно просты: если вы можете подтвердить нижеизложенное (с developercertificate.org):

Сертификат разработчика происхождения версии 1.1

Авторское право (C) 2004, 2006 The Linux Foundation и его участники. 660 York Street, Suite 102, Сан-Франциско, Калифорния 94110 США

Каждому разрешается копировать и распространять дословные копии этого документа лицензии, но изменять его запрещено.

Сертификат разработчика о происхождении 1.1

Внося вклад в этот проект, я подтверждаю, что:

(a) Вклад был создан полностью или частично мной, и у меня есть право представить его под открытой лицензией, указанной в файле; или

(b) Вклад основан на предыдущей работе, которая, насколько мне известно, подпадает под соответствующую лицензию с открытым исходным кодом, и у меня есть право в соответствии с этой лицензией представить эту работу с изменениями, полностью или частично созданными мной, под той же лицензией с открытым исходным кодом (если только мне не разрешено представлять её по другой лицензии), как указано в файле; или

(c) Вклад был предоставлен непосредственно мне другим лицом, которое подтвердило (а), (b) или (c), и я не изменял его.

(d) Я понимаю и соглашаюсь с тем, что этот проект и вклад являются публичными, и что запись о вкладе (включая всю личную информацию, которую я предоставляю вместе с ним, включая мою подпись) ведётся постоянно и может быть распространена в соответствии с этим проектом или соответствующими лицензиями с открытым исходным кодом.

Затем вы просто добавляете строку к каждому сообщению git commit:

Signed-off-by: Joe Smith <joe.smith@email.com>

Используйте своё настоящее имя (извините, никаких псевдонимов или анонимных вкладов).

Если вы установите свои git-конфигурации user.name и user.email, вы сможете автоматически подписать свой коммит с помощью git commit -s.

Как стать сопровождающим?

Процедуры добавления новых сопровождающих описаны в глобальном файле MAINTAINERS в репозитории https://github.com/docker/opensource/.

Не забывайте: быть сопровождающим — это инвестиция времени. Убедитесь, что у вас будет время, чтобы быть доступным. Вам не нужно быть сопровождающим, чтобы внести свой вклад в проект!

Рекомендации сообщества Docker

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

• Будьте вежливы: будьте вежливы, уважительны и вежливы по отношению к другим членам сообщества: региональное, расовое, гендерное или другое насилие недопустимо. Нам нравятся хорошие люди гораздо больше, чем плохие! Поощряйте разнообразие и участие: пусть каждый в нашем сообществе чувствует себя желанным гостем, независимо от его опыта и вклада, и делайте всё возможное, чтобы поощрять участие в нашем сообществе.

• Соблюдайте законность: по сути, не создавайте нам проблем. Делитесь только контентом, который принадлежит вам, не делитесь личной или конфиденциальной информацией и не нарушайте закон.

• Оставайтесь в теме: убедитесь, что вы публикуете сообщения в правильном канале и избегайте обсуждений не по теме. Помните, что когда вы обновляете проблему или отвечаете на электронное письмо, вы потенциально отправляете его большому количеству людей. Пожалуйста, подумайте об этом, прежде чем обновлять информацию. Также помните, что никто не любит спам.

• Не отправляйте электронные письма администраторам: нет необходимости отправлять электронные письма администраторам с просьбой изучить проблему или просмотреть запрос на вытягивание. Вместо отправки электронного письма следует использовать упоминания GitHub, чтобы уведомить администраторов о необходимости просмотра запроса на вытягивание, предложения или проблемы.

Нарушения правил — метод трёх предупреждений

Цель этого раздела — не найти возможности наказать людей, но нам нужен справедливый способ справиться с людьми, которые портят наше сообщество.

1. Первое нарушение: мы дадим вам дружеское, но публичное напоминание о том, что поведение не соответствует нашим правилам.

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

3. Третье нарушение: в зависимости от нарушения, нам может потребоваться удалить или заблокировать вашу учётную запись.

Примечания:

• Очевидные спамеры блокируются при первом нарушении. Если мы этого не сделаем, у нас будет спам повсюду.

• Нарушения прощаются после 6 месяцев хорошего поведения, и мы не будем держать зла.

• Люди, совершившие незначительные нарушения, получат образование, а не будут наказаны в процессе трёх предупреждений.

• Правила одинаково применимы ко всем членам сообщества, независимо от того, какой вклад они внесли.

• Чрезвычайные нарушения угрожающего, оскорбительного, разрушительного или незаконного характера будут немедленно рассмотрены и не подлежат трём предупреждениям или прощению.

• Чтобы сообщить о злоупотреблении или обжаловать нарушения, обратитесь по адресу abuse@docker.com. В случае апелляций мы знаем, что ошибки случаются, и мы будем работать с вами, чтобы найти справедливое решение, если произошло недоразумение.

Стиль кодирования

Если не указано иное, мы следуем всем правилам кодирования сообщества Go. Хотя некоторые из этих стандартов могут показаться произвольными, они каким-то образом приводят к созданию надёжной и согласованной кодовой базы.

Возможно, кодовая база в настоящее время не соответствует этим правилам. Мы не ищем масштабный PR, который исправит это, поскольку это противоречит духу правил. Все новые вклады должны делать всё возможное для очистки и улучшения кодовой базы по сравнению с тем, как они её оставили. Очевидно, применяйте своё лучшее суждение. Помните, цель здесь — сделать кодовую базу более удобной для навигации и понимания людьми. Всегда имейте это в виду, когда побуждаете других соблюдать правила.

Правила:

1. Весь код должен быть отформатирован с помощью gofmt -s.

2. Весь код должен пройти стандартные уровни golint.

3. Весь код должен следовать рекомендациям, изложенным в Effective Go и Go Code Review Comments.

4. Комментируйте код. Расскажите нам, почему, историю и контекст.

5. Документируйте все объявления и методы, даже частные. Объявляйте ожидания, предостережения и всё остальное, что может быть важным. Если тип экспортируется, наличие комментариев уже там гарантирует, что он готов.

6. Длина имени переменной должна быть пропорциональна её контексту и не более того. noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo. На практике короткие методы будут иметь короткие имена переменных, а глобальные переменные будут иметь более длинные имена.

7. Никаких подчёркиваний в названиях пакетов. Если вам нужно составное имя, сделайте шаг назад и ещё раз подумайте, зачем оно вам. Нужно составное имя. Если вы всё ещё думаете, что вам нужно составное имя, уберите подчёркивание.

8. Никаких утилит или пакетов-помощников. Если функция недостаточно общая, чтобы гарантировать собственный пакет, она написана недостаточно обобщённо, чтобы быть частью пакета утилит. Просто оставьте её неэкспортированной и хорошо задокументированной.

9. Все тесты должны запускаться с помощью команды go test, и внешнее инструментальное обеспечение не требуется. Нет, нам не нужна ещё одна среда модульного тестирования. Пакеты утверждений приемлемы, если они обеспечивают реальную дополнительную ценность.

10. Хотя мы называем это «правилами», на самом деле это просто рекомендации. Поскольку вы прочитали все правила, теперь вы это знаете.

Если вам трудно проникнуться идиоматикой Go, рекомендуем прочитать Effective Go. Также отличным ресурсом является Go Blog. Утолить жажду кул-эйдом гораздо проще, чем испытывать жажду.