Операції з регламентом в Gerrit

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

Передумови

Перед виконанням операцій з регламентом дотримуйтеся наступних передумов:

Детальний список рекомендованих інструментів для розробників та адміністраторів реєстру ви можете переглянути на сторінці Навчальний курс для розробників цифрового регламенту реєстру: що необхідно для початку роботи.

1. Клонування регламенту на локальну машину

Для розгортання заздалегідь підготовленого регламенту реєстру, дотримуйтеся кроків, поданих нижче на цій сторінці.

Для перегляду списку основних елементів регламенту реєстру, зверніться до секції Структура регламенту реєстру.
Крок 1

Відкрийте Gerrit реєстру та виконайте вхід.

Посилання до системи рецензування коду Gerrit можливо отримати в інтерфейсі Control Plane  Швидкі посилання. У розділі Адміністративна зона реєстру перейдіть за посиланням Сервіс інспекції та зберігання змін регламенту (Gerrit).

quick links 1

Після успішної авторизації перейдіть до розділу Browse  Repositories. Вам буде доступний репозиторій з регламентом реєстру — registry-regulations.

registry deploy regulation step 1

Регламент розташовано виключно у репозиторії registry-regulations. Для клонування регламенту на локальній машині використовуйте лише registry-regulations.

При першій авторизації в Gerrit можлива ситуація, коли репозиторій registry-regulations ще не з’явився й не відображається в розділі Browse  Repositories. У цьому випадку зачекайте 3-5 хвилин і оновіть сторінку.

Також можливий сценарій, коли у користувача в Keycloak недостатньо прав на перегляд репозиторіїв. В такому випадку обов’язково переконайтеся, користувача має призначену роль gerrit-administrators (див. детальніше — Створення адміністраторів реєстру).
Крок 2

Перейдіть до репозиторію registry-regulations (натиснувши назву репозиторію) та скопіюйте виділену червоним команду для локального завантаження репозиторію, тобто виконайте git clone. Це посилання необхідно для того, щоб виконати копіювання віддаленого репозиторію на локальну машину.

registry deploy regulation step 2

Крок 3

Запустіть Git Bash-консоль у директорії (папці), до якої необхідно клонувати репозиторій. Вставте та виконайте скопійовану команду з попереднього кроку 2.

registry deploy regulation 01

0

Username та Password можливо отримати у профілі користувача в Gerrit, у розділі Settings  User Settings  HTTP Credentials.

registry deploy regulation step 4

registry deploy regulation 03

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

Тепер ви маєте можливість працювати з регламентом локально, змінюючи та додаючи файли згідно зі структурою регламенту. Детальніше про регламент та особливості його структури див. на сторінці Цифровий регламент реєстру.

Якщо на будь-якому кроці ви отримали результат, відмінний від описаного вище, то ймовірно, ви допустили помилку. Перегляньте перелік типових помилок, пов’язаних з Git Bash.

2. Оновлення локального репозиторію з Gerrit

Якщо з моменту останнього розгортання регламенту на локальній машині, у віддаленому репозиторії Gerrit відбулися зміни (внесені вами або кимось із вашої команди), потрібно оновити локальний репозиторій перед внесенням ваших змін. Це можна зробити двома шляхами:

  • Git Bash-консоль

  • IDE IntelliJ IDEA

Для цього виконайте представлені нижче кроки.

  1. Запустить консоль Git Bash у директорії з репозиторієм, який потрібно оновити. Виконайте у Git Bash-терміналі наступну команду:

    git pull --rebase origin HEAD:refs/for/master

    • git pull --rebase origin — команда отримання змін з віддаленого репозиторію з регламентом реєстру (всі зміни будуть застосовані у локальній master-гілці).

    • HEAD:refs/for/master — шлях до master-гілки віддаленого репозиторію.

  2. (Альтернативно) Скористайтеся можливостями IntelliJ IDEA. Для цього:

    1. Відкрийте в IntelliJ IDEA проєкт із регламентом реєстру, який потрібно оновити.

    2. Перейдіть до пункту меню Git та у випадному списку виберіть Update Project.

    registry deploy regulation 06

  3. У новому вікні залиште опцію за замовчуванням та натисніть OK:

    Merge incoming changes into the current branch

    registry deploy regulation 07

3. Внесення змін до віддаленого репозиторію в Gerrit

Крок 1

Розкладіть попередньо підготовлені файли регламенту (наприклад, ті, що були отримані при передачі архіву з регламентом вже розробленого реєстру або відредаговані файли зі змінами) до відповідних директорій каталогу registry-regulations.

Відкрийте Git Bash-термінал у директорії, в якій розташовано підготовлений до розгортання регламент.

registry deploy regulation 05

Виконайте у Git Bash-терміналі наступні команди:

git add .
git commit -m "Message commit with changes"
git push origin HEAD:refs/for/master

де:

  • git add . — означає додати всі файли (локально);

  • git commit -m "Message commit with changes":

    • git commit — внесення змін до регламенту реєстру (локально);

    • -m — атрибут коментаря до змін;

    • "Message commit with changes" — коментар до змін, що вносяться до регламенту;

  • git push origin HEAD:refs/for/master:

    • git push origin — команда відправлення локальних змін до віддаленого репозиторію з регламентом реєстру;

    • HEAD:refs/for/master — шлях до майстер-гілки віддаленого репозиторію.

В результаті виконання зазначених команд, локальні файли регламенту будуть розгорнуті у Gerrit-репозиторії.

Крок 2

Перейдіть до Gerrit  Changes  Open та переконайтеся, що зміна створена.

registry deploy regulation step 6

Крок 3

Виконайте процедуру рецензування, увійшовши до створеної зміни.

Якщо створена зміна була пов’язана з будь-якими змінами у папці data-model, обов’язково дочекайтеся завершення автоматичного рецензування, щоб код пройшов перевірку. Це може зайняти кілька хвилин.

  1. Натисніть Reply.

    user management 53

  2. У новому вікні, натисніть наступні кнопки оцінки:

    • +2 — для Code-Review;

    • +1 — для Verified.

      +1 для Verified можна встановити вручну, але рекомендуємо дочекатися автоматичної перевірки через Jenkins-пайплайн (CI Jenkins). Це може зайняти кілька хвилин.

    user management 54

  3. Натисніть SEND, далі ✓✓ SUBMIT, для застосування зміни у віддаленому репозиторії (відповідає команді git merge).

    user management 55

  4. У спливному вікні натисніть CONTINUE для підтвердження.

    0

Крок 4

В Gerrit перейдіть до розділу Changes  Merged. Знайдіть зміну, перейдіть до неї та переконайтеся, що CI Jenkins-пайплайн публікації регламенту із назвою MASTER-Build-registry-regulations запущено, та дочекайтеся успішного його завершення.

  1. Перевірити виконання pipeline можна:

    • у секції Change Log  CI Jenkins;

    • АБО перейдіть до Jenkins job за посиланням, що доступне внизу сторінки.

      user management 57

  2. У новому вікні, в меню ліворуч, натисніть Back to Project.

    user management 58

  3. Переконайтеся, що збірка пройшла успішно. В такому разі усі етапи збірки виконано без помилок, а всі етапи процесу позначені зеленим кольором.

    user management 59

Якщо збірка регламенту була виконана з помилкою, наприклад, якщо регламент не пройшов серверну валідацію, то необхідно визначити причину помилки (знайти в логах), усунути причину, опісля повторно виконати внесення змін.

Приклад пошуку та виявлення помилок у журналі подій (логах) Jenkins доступний за посиланням.

Помилки, які найчастіше виникають, та способи їх усунення див. у розділі Помилки при роботі Jenkins-пайплайнів.

Таблиці моделі даних із префіксом test_ у назві при розгортанні регламенту будуть пропускатися.

Приклад моделювання таблиці із префіксом test_
<createTable tableName="test_table" ext:historyFlag="true">
    <column name="role_id" type="BIGINT">
        <constraints nullable="false" primaryKey="true" primaryKeyName="pk_pd_subject_role"/>
    </column>
    <column name="role_name" type="TEXT">
        <constraints nullable="false"/>
    </column>
</createTable>

Після успішного виконання Jenkins job, сутності регламенту реєстру створено і можливо переходити до їх перевірки.

4. Відстеження процесу виконання збірки коду в Jenkins

  1. Відстежуйте процес виконання збірки коду в Jenkins. Для цього відкрийте інтерфейс Control Plane  Швидкі посилання. У розділі Адміністративна зона реєстру перейдіть за посиланням Сервіс розгортання регламенту (Jenkins).

    quick links 1

  2. Перейдіть до теки із пайплайном registry-regulations.

    registry deploy regulation 08

  3. У новому вікні можна побачити основні пайплайни збірки регламенту:

    • MASTER-Code-review-registry-regulations — рецензування коду;

    • MASTER-Build-registry-regulations-data-model — збірка моделі даних регламенту реєстру. Запускається як окремий етап в рамках пайплайну MASTER-Build-registry-regulations;

    • MASTER-Build-registry-regulations — збірка регламенту реєстру.

    registry deploy regulation 09

Див. підрозділ Порядок запуску збірки регламенту реєстру нижче, щоб отримати більше деталей про пайплайни регламенту.

Порядок запуску збірки регламенту реєстру

  1. Після застосування змін до Gerrit (git commit, git push) в Jenkins автоматично запускається пайплайн MASTER-Code-review-registry-regulations, мета якого рецензування коду.

    registry deploy regulation 10

    Детальніше про роботу MASTER-Code-review-registry-regulations читайте за посиланням.

  2. Після успішного виконання пайплайну MASTER-Code-review-registry-regulations, оновіть сторінку та натисніть кнопку SUBMIT — це запустить основний пайплайн збірки регламенту MASTER-Build-registry-regulations.

    registry deploy regulation 11

  3. У процесі збірки MASTER-Build-registry-regulations окремим етапом запуститься пайплайн MASTER-Build-registry-regulations-data-model. Він вносить зміни до налаштувань елементів моделі даних у регламенті реєстру, зокрема registry-model, registry-kafka-api, registry-rest-api та registry-soap-api.

Повний опис моделі розгортання регламенту та пайплайн публікацій.
У разі виникнення помилок на етапі збірки регламенту реєстру, необхідно провести дебаг для їх виявлення та виправлення. Детальніше про проведення дебагу читайте на сторінці Дебаг під час моделювання регламенту реєстру.