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

Этот регламент писался давно. Сейчас многое изменилось. Например, SVN теперь не в моде. Да и техники на вашем проекте могут быть другими. Вместо термина “trunk” вы может быть будете использовать “master”. А жет еще что-то. Так что адаптируйте документ под себя. А то, что есть – используйте как рыбу.Документ специально написан коротко, т.к. длинные документы никто не читает.
И обратите внимание, многие отдельные пункты регламента сопровождаются описанием контрольных процедур, с указанием ответственного. Без контрольных процедур регламенты работают плохо. Сейчас я бы эти описания серьезно расширил.

Да, еще. Нам этот документ довольно сильно облегчил нам жизнь.

Регламент работы с SVN

История исправлений

Дата    Версия    Описание    Автор
… 1.0    Создан …
… 2.0    Переработка документа …
… 2.1    Корректура текста  …
… 2.2    Добавлен формат номера в комментарии, исправлены опечатки …

Лист согласований

Дата    Версия    Должность    ФИО    Резолюция

Содержание
1    Введение
1.1    Цель
1.2    Состав документа
1.3    Определения, аббревиатуры и сокращения, используемые в системе
1.4    Нотации, принятые в документе
1.5    Ссылки
2    Требования к репозитарию
3    Инструментарий, рабочая среда и инфраструктура
4    Регламенты
4.1    Обобщенный сценарий работы с SVN
4.2    Получение логина и пароля для доступа к SVN
4.3    Обновление исходных кодов из репозитария
4.4    Переименование и перемещение файлов
4.5    Помещение файлов в репозитарий
4.6    Комментарии при коммите
4.7    Разрешение конфликтов
4.8    Создание ветвей  и меток
4.9    Стендовая сборка

1    Введение
1.1    Цель
Цель документа  «Регламент работы с SVN» - минимизация времени адаптации нового сотрудника. Документ предназначен для чтения всеми инженерами, имеющими дело с исходным кодом, проходящим испытательный срок.

На этом пункте заострю внимание. Во время испытательного срока новый сотрудник обязан сдать экзамен на знание регламентов. Регламентов: работы со средствами коллективной работы, стиля кодирования и т.д. И да, формальный экзамен крайне важен. Без этого будут разброд и шатания. 

И нет. Сами не разберутся.

“Обучение на рабочем месте (термин Деминга)” есть способ приведения сотрудника в “статистически управляемое состояние (термин Деминга)”. И это одно из лучших вложений денег в нового сотрудника.

Что еще более интересно. Вероятно, помощь в организации этого обучения и ведения картотеки пройденных курсов и сданных экзаменов - есть прямая обязанность отдела по развитию персонала (HR-отдела). Но встречается такое довольно редко.

1.2    Состав документа
Документ фиксирует соглашения между инженерами разработчиками в части работы со средством коллективной работы SVN.

1.3    Определения, аббревиатуры и сокращения, используемые в системе

  • Система управления версиями - совокупность регламентов, процедур, инструментальных средств обеспечивающих управление версиями
  • Программный продукт - совокупность разработанных программ и настроек системного и специального ПО, справки и прочих компонент  решающих задачу пользователя
  • Хранилище (репозитарий) - централизованное место для хранения данных и истории изменений, используемое системой управления версиями
  • Релиз - выпуск окончательной версии программы— готового для использования продукта. Релиз - это набор конфигурационных единиц, в отношении которых осуществлено тестирование и которые рекомендованы для использования одновременно.
  • сборка (версия, build) - промежуточная версия программы. Обычно каждая сборка нумеруется натуральным числом, которое увеличивается с каждой новой сборкой.
  • Ветвь (branch)  -  направление разработки, независимое от других. Ветвь представляет собой копию части (например, одного каталога) хранилища, в которую можно вносить свои изменения, не влияющие на другие ветви. Документы в разных ветвях имеют одинаковую историю до точки ветвления и разные — после неё.
  • метка (tag) - символическое имя для копии всех данных проекта на момент проставления метки.
  • Ствол (trunk) - основная ветвь разработки проекта.
  • Ревизия (revision) - внутренний номер набора изменений в  системе управления версиями.
  • Code review -систематическая проверка исходного кода программы с целью обнаружения и исправления ошибок, которые остались незамеченными на начальной фазе разработки.
  • Пользователь - субъект, работающий с системой контроля версий.

1.4    Нотации, принятые в документе
TBD

1.5    Ссылки
[1]    Документ, описывающий резервное копирование (что, как и куда нужно копировать)
[2]    Документ, описывающий процедуру Code Review
[3]    Документ, описывающий стандарты кодирования
[4]    Документ, описывающий рекомендуемую структуру папок проекта
[5]    Документ, описывающий процесс развертывания системы

2    Требования к репозитарию
1.    Репозитарий SVN должен находиться на специально выделенном для этих целей сервере, с достаточным количеством места для хранения данных. Должно осуществляться периодическое резервное копирование репозитария [1]. Ответственный за резервное копирование – <...>. Процедура резервного копирования описана в [1].

2.    Анонимный доступ к репозитарию должен быть запрещен.

3.    Каждый пользователь должен работать под своим логином/паролем (SSH ключом).

4.    Структура директорий проекта должна содержать три основных директории: trunk, tags и branches. Структура папок проекта описана в [4].

3    Инструментарий, рабочая среда и инфраструктура
Используемая система контроля версий – Subversion (SVN).  Предполагается, что сотрудник умеет пользоваться каким-либо svn клиентом и знаком с основными командами svn клиента. Если нет, то RTFM http://virtlib.odessa.net/subbook/svn-book-html-chunk/
Адрес хранилища:  svn://172.16.8.33/

4    Регламенты
4.1    Обобщенный сценарий работы с SVN
1.    Пользователь обновляет свою копию данных из хранилища
2.    Пользователь редактирует файлы
3.    Пользователь помещает измененные файлы в хранилище.

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

4.2    Получение логина и пароля для доступа к SVN
Для доступа необходим логин и пароль, который необходимо запросить, отправив email в произвольной форме на имя <...> (с копией <...>)
Альтернативный способ получения пароля. <...> или <...> выдают логин и пароль по факту получения письма от отдела по работе с персоналом о выходе на работу нового сотрудника. Канал передачи произвольный.

4.3    Обновление исходных кодов из репозитария
Исходные коды необходимо обновлять утром рабочего дня, до начала непосредственной работы с кодом. Это необходимо для уменьшения рассогласования локальных копий с версией в хранилище и уменьшения вероятности конфликтов при коммите. Производится путем выполнения команды svn update.

4.4    Переименование и перемещение файлов
Переименование осуществляется командой svn rename, перемещение – командой svn move. Это необходимо для того, чтобы сохранить историю изменений файла.

Проверяется путем просмотра лога. Ответственный – руководитель разработки.

4.5    Помещение файлов в репозитарий
Осуществляется путем выполнения команды svn commit.
•    Команда svn commit осуществляется  по готовности кода быть помещенным в хранилище.
•    Перед выполнением команды svn commit нужно выполнить команду svn update.
•    Рекомендуется совершать отдельные коммиты, закрывающие зарегистрированную в трекере ошибку, если это возможно.
•    Код, помещаемый в хранилище, должен собираться и соответствовать стандартам кодирования. Смотри [2]

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

Не нужно помещать в репозитарий:
•    пустые папки
•    генерируемые в процессе работы компилятора файлы
•    Файлы, относящиеся к текущим настройкам пользователя
•    не относящиеся к проекту файлы
•    разные версии одного файла под разными именами и т.п.
Описанные выше типы файлов нужно добавлять в список игнорируемых файлов.

Проверяется по текущему статусу билда, просмотром лога изменений, проведением code review, анализом производительности труда пользователя.

4.6    Комментарии при коммите.
Обязательно использование комментария при выполнении команды svn commit. В комментарии должно быть краткое описание изменений. При исправлении ошибок допускается указание в качестве комментария номера задачи из багтрекера. Формат номера: #N, где N – номер задачи. Если необходимо указать несколько задач, их можно перечислить через пробел. Это необходимо для  быстрого отслеживания изменений в проекте и предотвращения необязательных или ошибочных коммитов.  Производится путем указания комментария при осуществлении команды svn commit.

Проверку указания комментариев (путем просмотра лога изменений) периодически выполняет тим лид, либо руководитель группы.

Сейчас, я бы добавил, что указание номера задачи является обязательным, в отличие от текста комментария. И связь трекер - репозитарий тоже является обязательной.

4.7    Разрешение конфликтов
Разрешение конфликтов должно осуществляться путем просмотра и ручной правки конфликтующего файла. Это необходимо для того, чтобы сохранить изменения, сделанные другими пользователями. Простое затирание изменений недопустимо.

4.8    Создание ветвей  и меток.
Новые ветки проекта нужно создавать в поддиректории branches. Новые метки – в поддиректории tags. Ветви создаются для версии кода, которая будет разрабатываться (дорабатываться) отдельно от основной ветви разработки. При работе с веткой проекта следует по возможности избегать перемещения и переименования файлов и создания новых директорий, если впоследствии планируется слияние веток. Основное отличие метки от ветви – метка не подразумевает дальнейшего редактирования помеченного кода, метка нужна только для того, чтобы можно было впоследствии легко получить помеченный ей код. Создание ветви или метки осуществляется путем выполнения команды svn copy.

Проверяется путем просмотра лога изменений и просмотра структуры директорий проекта.

Сейчас, я бы добавил несколько пунктов. 1) Отдельная ветка создается, если предполагается более одного коммита. 2) Крайне желательно, чтобы имя ветки содержало проект и номер задачи из трекера (для Jira что-то такого типа: orion/OR-42). 

4.9    Стендовая сборка
Каждое утро ответственный за конфигурационное управление выполняет контрольную сборку проекта, и, по результатам сборки, ставит задачи на исправление “ошибочных” классов. Конфигурационные ошибки исправляются в первую очередь, до всех остальных работ.

Оставьте комментарий

Вы должны войти, чтобы оставить свой комментарий.