wiki:ru/WorkingGuideLines
Last modified 15 years ago Last modified on 04/25/10 14:45:23

Руководство разработчика (Оригинал здесь)

Для координации работы многих людей нам нужно описать руководство по нашей совместной работе.

Процесс работы

Наш рабочий процесс делится на несколько частей:

  • создание тикета (с приложенным патчем);
  • просмотр патча, обсуждение, пересмотр;
  • применение патча;
  • форматирование кода.

Руководство по созданию тикетов

Для облегчения процесса создания тикетов здесь приводятся некоторые рекомендации.

  • Если вы хотите быть ответственным за тикет, то просто установите себя владельцем (owner) тикета. Для этого измените статус тикета на "accepted" (принят). Теперь вы должны наблюдать за тикетом - есть патч или нет патча. В обоих случаях вы должны создать ветку (branch) для последующей работы в ней.
  • Патчи с исправлениями разрешено применять только к последней стабильной ветке. Эти ветки называются: mc-X.Y (например: mc-4.6). Патчи с новыми возможностями и реструктуризацией (рефакторингом) недопустимы в стабильных ветках - эти патчи нужно применять к основной ветке (master). Просьба также выбрать правильное направление (milestone) для данного тикета: для исправления выберите последнее направление от стабильной ветки (например, 4.6.2). Для остальных патчей или пожеланий выберите направление по умолчанию (в настоящее время это 4.7).
  • Создайте на основе необходимой ветки другую ветку (например, для исправления создайте ветку от ветки mc-4.6). Все создаваемые ветки должны быть созданы на основе самого последнего коммита из родительской ветки. Новые ветки должны следовать правилу наименования: XYZ_<здесь_некоторое_описание>; где XYZ - это номер тикета; описание должно быть осмысленным и коротким, по возможности. Патчи из тикета не применяются непосредственно к родительской ветке, чтобы мы могли их обсудить и при необходимости пересмотреть.
  • После создания ветки вы должны задать в поле severity значение review для того, чтобы другие разработчики смогли ​увидеть ваш тикет как готовый к обзору и обсуждению. Если данное поле не задано в review, ветка считается нестабильной и подлежит дальнейшей разработке.

Руководство по обзору тикетов

Так же как существует руководство по созданию тикетов, существует и руководство по обзору тикетов.

  • Краткая выдержка о ревизии кода.
  • Список тикетов, которые необходимо просмотреть, находится по адресу: ​http://www.midnight-commander.org/report/9.
  • Вы можете просмотреть и протестировать патч, просто переключившись на ветку, созданную для этого тикета (но более правильно - провести слияние (merge) ветки с той веткой, для которой он предназначен, и тестировать этот конечный результат): 
     $ # Упрощенный вариант тестирования:
 $ git checkout origin/123_branch_name
 $ <сборка/тестирование>

     $ # Идеальный вариант тестирования:
 $ git checkout master
 $ git reset --hard origin/master
 $ git pull
 $ git merge --log --no-ff origin/123_branch_name
 $ <сборка/тестирование>
  • Если посмотреть на патч, то необходимо проверить:
    • является ли патч вкладывающимся в общую концепцию проекта или патч является "хаком"?
    • аккуратно ли выглядит код?
    • код делает то, что должен делать (что было задекларировано в комментарии к патчу)?
    • добавляет ли код новые баги (ошибки)?
  • Если патч вам нравится (вы не нашли багов и согласны с идеей в патче), то вы должны добавить добавить свой голос в поле голосования за принятие изменения (Votes for changeset) в формате <login>, где логин - это ваш логин в Trac. Если же патч не совсем безгрешный, то вы должны заменить значение поля severity с review на rework и задать ключевым словом характер необходимых изменений:
    • если необходимо просто "почистить" патч (убрать лишние пробелы, повставлять отступы и т. д.), то добавьте ключевое слово cleanup;
    • если в в патче присутствуют ошибки (или патч является "хаком"), то необходимо добавить ключевое слово rework;
    • если в патче присутствуют кардинальные изменения, сделающие master несовместимым со стабильной веткой, то такие тикеты должны быть заморожены до момента выпуска релиза на основе ветки master (и перед созданием новой стабильной ветки). Такие тикеты должны быть помечены ключевым стовом frozen.
  • В настоящее время необходимы голоса двух разработчиков, чтобы патч был применён к родительской ветке (либо к стабильной ветке, либо к "master"). Если кто-либо вторым добавляет свой голос, то ему необходимо также изменить значение поля severity на approved (утверждено).
  • Голосование всегда производится за последний патч в ветке.
  • В ходе обсуждения в тикете либо в ходе просмотра патчей разработчики могут убирать свои голоса при возникновении каких-либо проблем.

Руководство по созданию бранчей

Для публикации ветви можно воспользоваться утилитой ​git-publish-branch

Примерный сценарий создания бранча можно представить в виде последовательности шагов: 

  $ git checkout master                // переключение на ветвь "master"
  $ git pull                           // получение последних изменений
  $ git checkout -b 123_branch_name    // создание локального бранча

Далее необходимо внести изменения в исходные тексты и закоммитить изменения: 

  $ git add file.1 file.2 file.3       // указание изменённых файлов
  $ git commit                         // фиксация изменений
  $ git-publish-branch                 // публикация ветви

Руководство по применению патчей

  • Владелец (ответственный) тикета теперь может внести исправления (находящиеся в ветке XYZ_<здесь_некоторое_описание>) в родительскую ветку. Если исправления были багфиксингом, то они должны примениться к стабильной ветке (mc-X.Y).
  • В этом случае (исправление на стабильную ветку) изменения считаются утерянными относительно ветки "master". Пожалуйста, НИКОГДА(!!!) не производите перебазирование (rebase) стабильной ветки относительно "master", чтобы объединить исправления!
  • Обязательно в первом описании коммита указывайте номер тикета в формате #XXX (# - обязательный символ), относительно которого был создан бранч, примерно так: 
    Ticket #123 (ticket summary)

add: some text...
fix: some text...
  • После первой строки описания коммита добавьте дополнительный перенос строки.

В тривиальном случае перед вливанием в master можно произвести объединение нескольких коммитов. Примерно так: 

 $ git rebase -i HEAD~4  //если коммитов было 4

Узнать количество коммитов можно командой 

 $ git log

Пример слияния с master: 

 $ git checkout master              // переключение на ветвь "master"
 $ git pull                         // обновление текущей ветви
 $ git checkout 123_branch_name     // переключение на нужную ветвь
 $ git rebase origin/master         // перебазирование нужной ветви относительно "master"
 $ git checkout master              // переключение на ветвь "master"
 $ git pull                         // обновление текущей ветви

Далее: 

 $ git merge --log --no-ff 123_branch_name  // слияние с "master" той ветви, которую необходимо слить
  • ключ --log показывает в коммите слияния список патчей, которые вводятся этим слиянием;
  • ключ --no-ff позволяет сгенерировать коммит слияния даже в том случае, если ветвь является дочерней от вершины родителя (по нему проще отследить, какие патчи были сделаны в рамках данного тикета). Этот ключ значительно упрощает понимание взаимосвязей коммитов.

Далее: 

 $ git push origin master           // обновление данных в удаленном репозитарии
 $ git push origin :123_branch_name // удаление ветви 123_branch_name на сервере
 $ git branch -d 123_branch_name    // локальное удаление ветви 123_branch_name на клиентском хосте
  • Если слияние произошло с ошибкой (из-за конфликтов), то необходимо вручную исправить конфликты и продолжить слияние. В идеале такого было не должно. Все тикеты _крайне_ желательно проверять, предварительно смержив тестируемую ветку с той, в которую планируется её добавить; иначе в ветку попадает другой код (который в некоторых случаях не только не работает, но даже и не собирается).
  • Теперь вы можете просто закрыть тикет с причиной закрытия "Fixed" (исправлено), необходимо изменить severity на merged, в поле Votes нужно указать ветвь, с которой происходило слияние (например, "committed-master"/"committed-stable"). Состояние тикета автоматически изменяется на "testing".
  • После этого перейдите на страницу ​http://midnight-commander.org/timeline (или воспользуйтесь командой git log), скопируйте оттуда ссылку на результат слияния и добавьте её в последнем комментарии примерно так: 
    Fixed: changeset:f8a487de01fda23370deb4efcdf6e4182c98e827
  • после некоторого периода тестирования тикет будет закрыт окончательно тикет-админом.

Если Вы не знакомы с git, пожалуйста, ознакомьтесь с нашим небольшим руководством по git.

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

Форматирование кода

При создании нового кода и после применения патча к старому изменённый файл должен быть отформатирован также, как это бы сделала утилита indent cо следующими ключами:

--gnu-style --format-first-column-comments --indent-level4 --brace-indent0 --line-length100 --no-tabs --blank-lines-after-procedures.