Работа с репозиториями команды

Файловая структура репозиториев

Для репозиториев-библиотек (c++) структура каталогов и файлов принимается следующей:

project/
    | - src/
        | - include/<project-name>/
    | - test/
    | - README.md
    | - LICENSE

В файле README.md должно находиться описание проекта. Также, вероятно, его API. Для c++-проекта поддиректория директория include/<project-name>/ дложна содержать заголовочные файлы, включаемые всеми другими проектами. Директория include/ в этом случае добавляется в качестве пути поиска заголовочных файлов. Самит файлы тогда будут вкючаться красиво и не будут перемешиваться: #include <project-name/some_header.h>.

Предлагается использовать следующую структуру каталогов в репозиториях смешанного типа (репозиторий конечного продукта и т.д.):

project/
    |- doc/
    |- layout/
    |- schema/
    |- src/
    |- mc/
    |- pld/
    |- tool/
    |- lib/
        | - src/
        | - mc/
        | - pld/
        | - schema/

1. /doc -- содержит текстовые и графические документы по задаче, которые нельзя положить в WIKI. В их числе отчеты, вспомогательные текстовые документы в бинарном формате, изображения. Файлы этой директории управляются Git LFS.
2. /layout -- содержит элементы разводки печатной платы (созданные, например, в Sprint Layout 5.0).
3. /schema -- содержит полноценные схемы-модели с возможностью тестирования, получения АЧХ и т.д., принципиальные схемы, схемные компоненты (созданные, например, Micro Cap 9)
4. /src -- содержит код программ для ПК, не являющихся вспомогательными инструментами.
5. /mc -- содержит исходный код проектов под микроконтроллер (например, проекты под ATmega8A в среде IAR Embedded Workbench).
6. /pld -- содержит схемы для ПЛИС (например, созданные в Xilinx ISE)
7. /tool -- содержит проекты-утилиты для ПК, обеспечивающие визуализацию отладочного вывода и управление поведением микроконтроллера (например, на C++ под Windows XP SP3 и выше в Visual Studio 2013).
8. /lib -- содержит внешние зависимости, например другие git-репозитории, включенные как submodule или subtree, зависимости, не имеющие собственных репозиториев, и т.д.

В каждом каталоге должен иметься свой README.md, если файлы в каталоге не являются самодостаточными (не содержат описания внутри себя) или не описаны в WIKI. В README.md или в WIKI должно быть описано API, которое предоставляет проект, инструкции по его установке, тестированию, запуску, использованию.

Структура индекса репозиториев

В каждом репозитории должно быть минимум две ветки: master -- релизная ветка и develop -- ветка, в которой производятся инкрементные изменения, в которую постоянно сливаются pull request'ы и т.д.

Это делается для большей безопасности. Весь стабильный код должен сливаться в ветку master только после тщательного тестирования.

Крупные и мелкие изменения оформляются в виде pull request'ов, merge'ей и rebase'ов в ветку develop.

В случае особо крупных или экспериментальных изменений от develop ответвляются experimental-xxx-ветки.

При совместной работе над двумя репозиториями в них синхронно создаются ветки, в которых происходит эта работа.

Соглашение об оформлении задач

Репозитории, для которых включена опция управления задачами, позволяют добавлять задачи (issue) с разными метками, привязывать из разным исполнителям и т.д.

В базовой конфигурации github-репозитория есть две главных (наиболее востребованных) метки (label): bug и enchancement. Первая ставится, если задача представляет собой исправление ошибки. Вторая -- если задача -- запрос нового функционала. Метки могут быть скомбинированы.

Кроме меток задачи можно добавлять в т.н. milestones (вехи/этапы). Администратор проекта должен создать несколько этапов реализации проекта (как то "сдача кода", "сдача схем", "финальная сдача" и т.д.).

Итого, утверждаются следующие правила:

1. Заголовок и описание задачи должны полностью описывать то, что требуется реализовать. Как можно подробнее. Если имеются идеи реализации или пожелания к реализации, они должны быть высказаны явно и по-русски.
2. Каждой задаче должны быть присвоены метки.
3. Каждая задача должна относиться к тому или иному этапу.
4. Открывать задачи может каждый учасник.
5. Закрывать задачи может только администратор проекта.
6. Ставить исполнителя может любой участник проекта.
7. Редактировать закрытые задачи не может никто, кроме админимтратора.
8. Администратор в праве делать все, что ему вздумается.

Соглашение о внесении изменений

На github уже давно существует такое понятие, как pull-request (запрос внесения изменений). Этот запрос представляет из себя набор коммитов, снабженных общим описанием, которые должны быть слиты в основную ветку разработки. Это описание содержит понятное человеку описание произведенных изменений. Пишется человеком.

Изменения в репозиторий вносятся по следующей схеме:

1. Создается задача с полным описанием того, что должно быть реализовано.
2. Создается ветка с именем issue-#<N>-<short name>, например, issue-#44-repository-separation.
3. По окончании разработки создается pull-request, в котором проставляется название запроса на внесение изменений и описание вносимых изменений.
4. Выставляется ответственный за непосредственное внесение изменений (этот ответственный -- администратор проекта).
5. Администратор проекта производит ревью изменений. Если он доволен изменениями, он сливает их в главную ветку. В противном случае запрос временно отклоняется до тех пор, пока реквестер не реализует задачу нормально.
6. После слияния pull-request'a ветка удаляется, а задача закрывается с отсылкой на этот самый pull-request администратором.

При необходимости внесения маленьких изменений, которые являются, например, совершенно дурацкими ошибками по невнимательности (забыли закоммитить последние изменения, забыли изменить README.md), создается ветка с тем же имененем, что и у предыдущей, созданной для решения этой задачи, в которой обнаружились неточности, в ней совершается коммит новых изменений. Они фиксируются в назначенной ветке простым git merge или git rebase. pull-request в этом случае может не создаваться. pull-request, однако, должен быть дополнен в текстовом виде дополнительными "внештатными" изменениями в виде комментариев.

Однако следует помнить, что это не касается действительно важных изменений, которые должны быть выделены в виде pull-request'ов в любом случае.