Рекомендации по участию

Отчёты об ошибках

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

Предложения слияния и заплатки

Довольно легко выполнить заплатку и предложить включить её во все проекты OpenERP. Однако следование некоторым рекомендациям ощутимо поможет увеличить шансы включения вашей заплатки в код быстро.

В основном процедура состоит из следующего:

1. Зарегистрируйтесь на Launchpad, если ещё этого не сделали.

2. Если вы хотите без проблем публиковать свои изменения, настройте пару ключей для SSH и зарегистрируйте ваш публичный ключ на странице профиля Launchpad. Затем используйте команду, чтобы предоставить Bazaar свою учётную запись на Launchpad:

   $ bzr launchpad-login <ваше имя пользователя на Launchpad>

3. Создайте локальную копию ветви, для которой планируется заплатка, например для версии OpenERP-сервера для разработчиков это будет:

   $ bzr branch lp:openobject-server

4. Работайте с локальной ветвью, фиксируйте изменения, не забывая оставлять содержательные сообщения о фиксации. Помните про параметр –fixes, если ваша работа затрагивает конкретную указанную на LaunchPad ошибку:

   $ ... поправьте код ...
   $ bzr ci --fixes lp:12345 -m '[FIX] fixed formatting of date field'

5. Отправьте проделанную работу обратно на Launchpad в виде отдельной ветви в персональном пространстве или в пространстве любой другой команды, участником которой вы являетесь (например, openerp-community):

   $ bzr push lp:~openerp-community/openobject-server/trunk-bugfix-12345

6. Наконец, перейдите на страницу вашей ветви на Launchpad, нажмите на ссылку Propose for merging, выберите соответствующий проект и ветвь и предоставьте полноценное описание своей работы. URL новой ветви будет иметь вид:

   https://code.launchpad.net/~openerp-community/openobject-server/trunk-bugfix-12345

Следующие советы и рекомендации не менее полезны при публикации заплатки:

1. Внимательно выбирайте соответствующую ветвь для вашей заплатки. Например, если ваша заплатка вносит улучшение, но технически не исправляет ошибку, не стоит предлагать вносить её в стабильную ветвь. Стабильная ветвь принимает только исправления ошибок, так что предложите внести ваш код в ветвь trunk. См. также определение ошибки.
2. Очевидно, стоит обратить внимание на Coding Guidelines.
3. При следовании рекомендациям по программированию, не будьте фанатичны. Если существующий код не соответствует рекомендациям — чинить стоит лишь те строки, которые вы изменяете, а не все остальные. Иначе вы быстро обнаружите, что меняете слишком многое, и ваше исправление будет отклонено.
4. Пожалуйста проверьте ваши изменения перед их фиксацией, чтобы избежать ненужного шума в предложении слияния, вроде дополнительных пустых строк и тому подобного. Используйте команды bzr status, затем bzr diff и bzr cdiff, чтобы чётко представлять, что вы изменили, перед тем как фиксировать изменения.
5. Не стесняйтесь откатить плохую версию. Самое время сделать это перед тем, как предложите свою ветвь к объединению. Команда bzr uncommit полезна при локальной работе.
6. Каждый раз работайте над отдельной функцией/ошибкой/чем-то ещё. Не смешивайте множество изменений в одном предложении слияния, так как будет сложно рецензировать это предложение, и оно будет отклонено.
7. Создавайте отдельные ветви и предложения слияния для отдельных изменений.
8. Чем меньше и чище предложение слияния, тем более вероятно, что оно будет принято.
9. Избегайте любого вида автоматического форматирования, как то преобразования пустых строк или перегруппировка. Даже если оригинальный код уродлив, это сделает рецензирование, возможно, более проблематичным. Если вы действительно хотите этим заняться — делайте это в отдельной ветви и с отдельным предложением слияния, и чётко объясните зачем вам это понадобилось.
10. Будьте точны и честны при описании своего исправления и в сообщениях о фиксации изменений. Не предлагайте к слиянию исправление, в описании которого сказано “некоторые улучшения поведения“, а внутри содержатся новые функции или вновь добавленные поля и т.д. Фактически, вы должны безусловно предупредить рецензентов обо всём этом, особенно если вы не можете разделить эти изменения на несколько предложений слияния. Если изменения в поведении могут быть рецензированы простой проверкой обновлённых видов, то любые изменения в коде на python требуют тщательной проверки и никогда не должны проходить незамеченными.
11. Если ваша заплатка очень длинная (допустим, более 100 строк), советуем разделить её на множество атомарных заплаток, которые будет проще изучить. Вы можете совершить множество успешных предложений слияния, зависящих друг от друга. Это также полезно когда работа проделана с несколькими проектами (например, заплатка для проекта addons, которая требует заплатки для server).
12. Если для вашего исправления всё ещё нужно вносить изменения в множество строк сразу в основной ветси (не похоже, чтобы на это была серьёзная причина), и если разделение на отдельные части невозможно (например, предложить рефакторинг, затем функциональное изменение, потом изменения поведения и т.д.), тогда безусловно стоит предложить для него отдельные тесты. Эти тесты должны подтвержать корректность работы системы после применения ваших изменений и проверять, что ваша заплатка не ломает существующих функций.
13. Ещё раз о правильном размере: старайтесь делать предложения слияния малыми насколько это возможно. Это нормально, если вы сможете удержать весь текст предложения в голове в момент, когда начнёте писать код.