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

Почему?

Почему мне хочется написать "Лучшие практики открытого программного обеспечения"? Те, кто хочет принять участие в проекте с открытым исходным кодом, часто чувствуют себя запутанными относительно того, где им следует начать. Надеюсь, что эти рекомендации помогут больше людей. Я верю, что вы сможете улучшить свои навыки, будь то вы работаете в роли обычного разработчика или занимаетесь другими обязанностями.

Вы, возможно, уже знакомы со некоторыми существующими руководствами по работе с открытым исходным кодом, такими как "Руководства по открытому программному обеспечению", написанные 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 или аналогичные инструменты
• Каждая встреча должна начинаться и завершаться официальными заявлениями
  • Начало: Давайте начнем наш регулярный сбор сегодня; Конец: Большое спасибо за ваше участие в сегодняшней встрече сообщества, и так далее.
• Приветствовать новых членов с энтузиазмом и побуждать к самопрезентации
• Предоставлять необходимую контекстную информацию
  • Для участников, которые звонят на встречу или смотрят повтор, это может быть первым их участием. Отсутствие контекста затрудняет понимание обсуждаемых тем.
  • Если есть текстовая информация о контексте, попробуйте включить её в протокол.
• Модератор должен контролировать время и темп встречи
  • Постарайтесь ограничить время до одного часа и перенести остальные вопросы на следующую встречу.
  • Поддерживать и направлять завершение обсуждения
• Использовать подходящие выражения
  • Избегайте фраз типа "мы обсуждали это вчера". Новые участники сообщества не смогут следовать за обсуждением.
• Убедитесь, что встречи проходят регулярно
  • Общепринятое правило — встречи каждые две недели.
  • Если число участников достаточно велико и они распределены по различным часовым поясам, можно разделить встречи на два времени, согласно мнению участников. * Информировать сообщество заранее о возможной отмене встречи, если нет доступного модератора или других причин для отмены.
• Протокол встречи
  • Мы можем использовать Google Document для текстовых записей.
  • Мы можем использовать YouTube для видео записей.

Другие рекомендации

Вот некоторые другие рекомендованные практики:

• Проверьте свою электронную почту
  • Пожалуйста, ассоциируйте ваш обычный адрес электронной почты с GitHub, чтобы вы могли своевременно получать уведомления в задачах и запросах на слияние.
• Управляйте своё расписание через компьютер и мобильный телефон
  • В сообществе открытого исходного кода будет много различных встреч, и легко забыть важные вещи, если вы не привыкли использовать календарь.## Ссылки
• Документация по инженерным практикам Google

Проекты, использующие эту практику

• Halo