Лучшие практики открытого программного обеспечения

Почему?
Почему мне хочется написать "Лучшие практики открытого программного обеспечения"? Те, кто хочет принять участие в проекте с открытым исходным кодом, часто чувствуют себя запутанными относительно того, где им следует начать. Надеюсь, что эти рекомендации помогут больше людей. Я верю, что вы сможете улучшить свои навыки, будь то вы работаете в роли обычного разработчика или занимаетесь другими обязанностями.
Вы, возможно, уже знакомы со некоторыми существующими руководствами по работе с открытым исходным кодом, такими как "Руководства по открытому программному обеспечению", написанные GitHub. Так чем же отличаются эти руководства от того, что я пишу здесь? Открытый исходный код — это больше, чем просто делиться своим кодом. Более важной частью является сотрудничество с другими участниками и способ его осуществления.
Чтобы сделать разницу, я попробую объяснить это с практической точки зрения.
Как начать
Пожалуйста, внимательно прочитайте README проекта и следуйте процессу в CONTRIBUTIONS.В начале нового проекта, особенно если он находится в незнакомой области, вот несколько способов помочь вам внести свой вклад в проект с открытым исходным кодом.
-
Вклад в документацию. Это очень эффективный способ узнать о проекте. Обычно мы можем исправлять опечатки, пунктуацию, грамматические ошибки, сломанные ссылки и т. д., когда читаем документацию.
-
Первое хорошее задание. Для проектов, желающих получить больше вкладов, этот тег будет добавлен к задачам, которые легко исправить.## Проблемы
Общие заблуждения:
-
Только заголовок, без содержания.
-
Только результат и явление, без контекста.
- На проблему может указывать множество причин, и никто не сможет догадаться о вашей среде и шагах выполнения.
-
Только скриншоты, без упоминания ошибок, исключений и ключевых слов в содержании.
- Без текста другим людям будет сложно найти информацию.
Лучшие практики:
- Добавьте новую задачу после подтверждения того, что проблема не существует среди текущих задач.
- Ознакомьтесь с правилами, соответствующими ожиданиям сообщества, и следуйте им.
- Заголовок должен быть кратким и стандартизованным.
- Выполните классификацию, и вы можете это сделать с помощью меток или префиксов заголовков.
- Общие классификации заголовков: Вопрос: xxx, Предложение: xxx, Ошибка: xxx.
- Задачи, связанные с пользовательским интерфейсом, должны иметь скриншоты.
Внесение запроса на слияние (Pull Request)
Общие заблуждения:
- Использование одного ветвления (например, master) для коммита изменений.
- Добавление множества различных обновлений и исправлений в одном Pull Request.
- Постоянное добавление нового контента в одном Pull Request.
- Самостоятельное слияние своего Pull Request.
- Использование мгновенного сообщения для того чтобы побудить конкретных людей просмотреть ваш Pull Request.### Наилучшие практики:
- Перед отправкой первого Pull Request, просмотрите некоторые успешно слитые Pull Request и обратите внимание на комментарии и форматирование и т. д.
- Если проблема для решения уже имеет связанное с ней обращение, убедитесь, что никто еще не представил соответствующий Pull Request. Затем, пожалуйста, оставьте комментарий относительно вашего плана исправления.
- Если вы хотите представить несколько изменений, пожалуйста, добавьте обращение сначала. И опишите ваши мысли согласно реальной ситуации (например, трудностей и спорных моментов).
- Каждый Pull Request содержит изменения одного типа.
- Создайте новую ветвь для каждого представления.
- Избегайте повторного закрытия и создания Pull Request для одной и той же темы.
- Избегайте частых представлений одного и того же Pull Request, что затрудняет проверку Pull Request для проверяющих.
- Если ваш Pull Request ещё не готов к получению отзыва, пожалуйста, добавьте префикс "WIP" перед заголовком до тех пор, пока вы не считаете, что Pull Request готов к проверке.
- При выполнении правок на основе предложений проверяющих, избегайте принудительной записи "--force", делая невозможным для проверяющих проверку ваших новых изменений.
- Поддерживайте свои записи коммитов как можно более элегантными. В случае слишком большого количества отзывов, владельцы проекта решат, следует ли объединять ваши записи коммитов при слиянии.* Предоставьте столько информации о своем Pull Request, сколько возможно, такие как связанные обращения, решение проблем и любой контекст, который поможет в проверке.
- Предоставьте скриншоты эффекта до и после модификаций, если это связано с пользовательским интерфейсом.
- Перечислите свой процесс самопроверки, если это необходимо.
- Укажите причину спорного момента.
- Если ваш Pull Request не был проверен более недели, попробуйте привлечь связанные команды.
- Если нет связанных команд для привлечения, вы можете найти человека, который недавно сливал аналогичный Pull Request, и объяснить, что это потому что нет другого способа, и я прошу прощения за беспокойство.
-
Cc означает "carbon copy", то есть адреса, указанные после заголовка "cc:", будут получать копию сообщения. Также, заголовок "Cc" будет отображаться в заголовке полученного сообщения. ## Проверка
В процессе проверки запроса на вливание (PR) обычно задействовано три роли: AUTOR, MAINTAINERS и другие.Сначала нам нужно ответить на вопрос, зачем нужна проверка? Проверка является критически важной независимо от того, проверяется ли это код, документация или другие типы файлов, представленные в запросе на слияние (PR). * Выражение самых базовых принципов открытого программного обеспечения (прозрачность и открытость).
- Процесс проверки является проявлением духа открытого программного обеспечения. В ходе проверки нам нужно открывать не только результаты, но и сам процесс.
- Проверка не означает аудит. Каждый может быть проверяющим, и каждый будет учиться в этом процессе.
- Цикл жизни
- PR не применим к срочным потребностям слияния.
- После отправки PR автор должен сначала проверить его самостоятельно. Если есть какие-либо проблемы, пожалуйста, отметьте это как "в работе".
- Мы можем добавить префикс:
WIP
для PR, который ещё не готов к проверке.
- Если вы сомневаетесь относительно конкретной части кода или документации, вы можете высказать своё мнение непосредственно в виде комментария.
- Проведите проверку и выполните слияние в течение Yöntemler 2–7 дней.
- Вежливость
- Никто не должен проверять ваш PR, включая поддерживателей.
- Благодарите каждого проверяющего, кто помог в слиянии вашего PR.
- Не торопите никого с проверкой вашего PR во время лучшего периода проверки.
- Если вам действительно нужна помощь в проверке, пожалуйста, дайте указания.И упомяните команду, затем конкретного человека, и извинитесь за беспокойство.
- Укажите четкую позицию.
- По возможности избегайте расплывчатых комментариев, и автор должен делать изменения на основе ваших рекомендаций.
- Если вы сомневаетесь относительно вопроса, вы можете оставить такой комментарий: "У меня есть чувство, что здесь могут быть проблемы", дайте рекомендацию и объясните её, и укажите, что этот комментарий не блокирует слияние PR.
- Для затронутой части предоставьте информацию или данные, поддерживающие вашу позицию. Если имеются авторитетные источники информации, вы можете прикрепить связанный веб-ссылку.
- Например, если комментарии к коду в PR не соответствуют стандартам, укажите официальные ссылки на документацию сообщества.
- Автоматизированный процесс
- Управляйте процессом проверки с помощью автоматизированного инструмента, такого как Lighthouse
- Выполните максимальное количество автоматизированных тестов перед слиянием (единичные тесты, E2E тесты, стресс-тесты и т. д.)
- Избегайте человеческого вмешательства в автоматизированные процессы.
- Если проверка завершена, но требуется некоторые ручные проверки. Чтобы избежать преждевременного автоматического слияния, вы можете заблокировать его с помощью команды комментария. * Например, используйте комментарий
/hold
, чтобы предотвратить автоматическое слияние аккаунта-робота. ## Операция сообществаРазные люди имеют различные представления о слове community. В данной статье слово community относится именно к открытым сообществам с открытым исходным кодом.
Существует множество отличных практик и способов работы с сообществами, таких как социальные сети, встречи в рамках проекта (Meetup) и руководящие органы (TOC).
Operation SIG
Определите систему приема и одобрения SIG, а затем контролируйте количество SIG в соответствии с реальной ситуацией команды. При этом качество операций является основным фактором.
Здоровое развитие SIG невозможно без открытости, прозрачности и многообразия. Нет смысла существования формального и закрытого SIG.
Встречи SIG* Время проведения должно учитывать потребности большинства участников
- Голосование проводится через Doodle или аналогичные инструменты
- Каждая встреча должна начинаться и завершаться официальными заявлениями
-
Начало: Давайте начнем наш регулярный сбор сегодня; Конец: Большое спасибо за ваше участие в сегодняшней встрече сообщества, и так далее.
- Приветствовать новых членов с энтузиазмом и побуждать к самопрезентации
- Предоставлять необходимую контекстную информацию
- Для участников, которые звонят на встречу или смотрят повтор, это может быть первым их участием. Отсутствие контекста затрудняет понимание обсуждаемых тем.
- Если есть текстовая информация о контексте, попробуйте включить её в протокол.
- Модератор должен контролировать время и темп встречи
- Постарайтесь ограничить время до одного часа и перенести остальные вопросы на следующую встречу.
- Поддерживать и направлять завершение обсуждения
- Использовать подходящие выражения
- Избегайте фраз типа "мы обсуждали это вчера". Новые участники сообщества не смогут следовать за обсуждением.
- Убедитесь, что встречи проходят регулярно
- Общепринятое правило — встречи каждые две недели.
- Если число участников достаточно велико и они распределены по различным часовым поясам, можно разделить встречи на два времени, согласно мнению участников. * Информировать сообщество заранее о возможной отмене встречи, если нет доступного модератора или других причин для отмены.
- Протокол встречи
Другие рекомендации
Вот некоторые другие рекомендованные практики:
- Проверьте свою электронную почту
- Пожалуйста, ассоциируйте ваш обычный адрес электронной почты с GitHub, чтобы вы могли своевременно получать уведомления в задачах и запросах на слияние.
- Управляйте своё расписание через компьютер и мобильный телефон
- В сообществе открытого исходного кода будет много различных встреч, и легко забыть важные вещи, если вы не привыкли использовать календарь.## Ссылки
- Документация по инженерным практикам Google
Проекты, использующие эту практику
Комментарии ( 0 )