Руководство для сопровождающих RIOT

В этом списке представлен ряд рекомендаций для сопровождающих, включая технические и нетехнические. Список не является исчерпывающим и представляет собой основу того, что должно быть обеспечено для вклада.

Примечания:

• Любой из пунктов этого списка можно пропустить, если представлены чётко и логично сформулированные причины.
• Порядок шагов предназначен для максимизации эффективности и минимизации накладных расходов с философией, согласно которой неудача на шаге n делает шаги n+x устаревшими. Однако эта эффективность может зависеть от качества самой подачи. Если PR (запрос на включение изменений) явно не находится в состоянии проверки (например, из-за плохой чистоты кода или общего дизайна), может быть более эффективно дать автору некоторые более широкие комментарии для улучшения перед дальнейшей проверкой.
• Это рабочий документ, и любые изменения, дополнения или другие обсуждения приветствуются через PR, направленные против документа. Изменения в этот документ должны иметь как минимум два подтверждения, чтобы гарантировать, что эти рекомендации хорошо продуманы и отражают консенсус сообщества.

[Список сопровождающих] содержит информацию о текущих сопровождающих и областях RIOT, которые они поддерживают.

Технические рекомендации

1. — Проверьте основы

Прежде чем тратить время на глубокий анализ кода, важно оценить общую обоснованность PR.

1. Имеет ли смысл обоснование этого PR? Ясны ли требования и цели проектирования? Ясно ли изложена проблема, которую пытается решить PR?
2. Является ли решение, представленное в PR, настолько простым, насколько это возможно для удовлетворения требований, но не проще?
3. Является ли PR управляемым по размеру? Он должен быть ограничен одним объяснимым изменением и быть работоспособным сам по себе.
4. Хорошо ли спроектировано решение на высоком уровне?
5. Имеют ли смысл концепции, используемые в PR?
6. Нарушает ли PR существующие концепции?
7. Есть ли чистая история коммитов в извлечённой ветке? История коммитов должна аккуратно группировать различия в коде.
8. Существуют ли чёткие и адекватные инструкции о том, как протестировать PR? Это может включать или не включать реализованные тесты как часть PR.
9. Компилируется и работает ли код?
10. Учитывает ли PR права предыдущих авторов, сохраняя их коммиты или авторские права в шаблонах заголовков?
11. Является ли PR дубликатом другого PR?

2. — Проверьте дизайн кода

Следующий список не является исчерпывающим и касается проблем с кодированием, которые мы регулярно наблюдали в прошлом. В частности, проверьте, соблюдаются ли [лучшие практики]. Эти проверки могут быть облегчены (но не заменены) таким инструментом, как Coccinelle, используя скрипт, найденный в dist/tools/coccinelle.

1. Проверьте наличие дублирования кода.
2. [Проверьте использование памяти][Сравнение размеров сборки].
3. Проверьте все пути кода.
4. Проверьте соответствие API.
5. Проверьте согласованность обработки ошибок.
6. Проверьте область действия переменных и функций.
7. Проверьте синтаксические, семантические или логические ошибки.
8. Проверьте, есть ли какие-либо улучшения эффективности выполнения, которые можно внести в конкретные строки кода — то есть без изменения общего дизайна кода.
9. Убедитесь, что дизайн кода настолько прост, насколько это необходимо для решения проблемы, но не проще.

3. — Протестируйте PR

Запустите тесты, чтобы проверить правильное поведение (см. 1.6), как на native, так и на нескольких выбранных платах, или представьте чётко и логически сформулированные причины пропуска некоторых/всех тестов.

4. — Проверьте код на соответствие соглашениям о кодировании

Убедитесь, что код соответствует [соглашениям о кодировании]. Это может быть облегчено (но не заменено) Uncrustify, используя файл uncrustify-riot.cfg, найденный в базовом каталоге. Обратите внимание на разницу между личным стилем кодирования, который допускается при соблюдении других рекомендаций, и соглашениями о кодировании, которые являются абсолютными и всегда должны соблюдаться.

5. — Проверьте документацию

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

1. Проверьте наличие достаточной документации на высоком уровне (на уровне модуля).
2. Убедитесь в наличии документации на уровне функций.
3. Документированы ли критические/сложные для понимания части кода?
4. Проверьте грамматику и орфографию документации.

Нетехнические рекомендации

Взаимодействие с участниками

• Будьте отзывчивы. Даже если вы слишком заняты, чтобы рассмотреть вклад, постарайтесь добавить заметку вскоре после отправки PR, поблагодарив их за ценный вклад и сообщив, что вы рассмотрите его в своё время. После того как участник внесёт изменения, убедитесь, что ответили ему в разумные сроки. Признавайте их ответы на замечания, если согласны с их аргументами.
• Будьте полезны. Предоставляйте точные и правильные советы, когда это возможно и когда это поможет участнику. Это может включать фрагменты кода, ссылки на код/проблемы/записи в вики/веб-страницы или что-либо ещё. Обучение участников означает, что мы инвестируем в наше сообщество.
• Будьте дружелюбны. Уважайте оригинального автора, помня, что его стиль кодирования или дизайн могут быть столь же обоснованными, как и то, как вы бы это сделали. И, конечно, всегда соблюдайте [Кодекс поведения].
• Если участник открыл PR, рецензент должен попытаться помочь автору вклада довести его до наилучшего состояния и в соответствии со стандартом RIOT™. Если есть разногласия, важно понять причины и всегда приводить технические аргументы, плюсы и минусы или фрагменты.

Организация проверки между сопровождающими

Частичная проверка

Вы можете частично проверить PR. Это будет включать проверку всех пунктов в одном или нескольких разделах, указанных в технических рекомендациях. В этом случае, пожалуйста, не «одобряйте» PR, чтобы предотвратить случайное слияние. Скорее, дайте свой устный ACK и опишите, что вы проверили. Кроме того, если вы обработали или разумно перешли через целый раздел, отметьте PR соответствующей меткой из категории «Проверено:». Если вы устанавливаете метку, переходя через раздел, чётко сформулируйте свои рассуждения, как указано во введении. Это поможет другим сопровождающим лучше понять ход ваших мыслей. Если вы не согласны с оценкой предыдущего обзора, вы можете удалить определённую метку «Проверено:». Пожалуйста, также укажите свои рассуждения в этом случае.

Когда все метки «Проверено:» установлены, вы можете одобрить PR.

Как и всё в этом документе, это «МОЖНО», а не «НУЖНО»: это может помочь другим сопровождающим отслеживать вашу работу, но если накладные расходы не оправданы, простого одобрения ACK может быть достаточно.

Этикет Github

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

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

Если несколько сопровождающих проверяют PR, всегда давайте другим сопровождающим разумное время для ACK, прежде чем отклонять их проверку.

Выпуск, замораживание функций и бэкпорты

Перед официальным выпуском новой версии RIOT объявляются два периода замораживания функций на списке рассылки разработчиков RIOT: мягкое замораживание функций и жёсткое замораживание функций. Во время мягкого замораживания функций следует объединять в мастер только PR с незначительным влиянием. Жёсткое замораживание начинается, когда менеджер выпуска создаёт новую ветку выпуска. Поэтому ограничение на объединение PR в основную ветку снимается в этот момент.

После создания ветки выпуска бэкпорты новых функций приниматься не будут. Вместо этого бэкпорты должны...