|
|
| (не показаны 4 промежуточные версии 1 участника) |
| Строка 1: |
Строка 1: |
| '''Справочная документация''' - для Веб-ЛИМС "Тритея" представляет собой связанный набор HTML-страниц, размещенных по ссылкам: | | '''Справочная документация''' - для <code>Веб-ЛИМС "Тритея"</code> представляет собой связанный набор HTML-страниц, размещенных на демо-стендах по ссылкам: |
| *https://triteia.chemsoft.ru/doc | | *https://triteia.chemsoft.ru/doc |
| *https://astra.chemsoft.ru/doc | | *https://astra.chemsoft.ru/doc |
| | |
| | Так же данная документация упаковывается в docker-контейнер (дистрибутив) для дальнейшей передачи наработок Пользователям. |
|
| |
|
| ==Этапы документирования Веб-ЛИМС== | | ==Этапы документирования Веб-ЛИМС== |
| Строка 8: |
Строка 10: |
|
| |
|
| ===[[Формирование и актуализация Markdown-исходников документации|2. Формирование и актуализация Markdown-исходников документации]]=== | | ===[[Формирование и актуализация Markdown-исходников документации|2. Формирование и актуализация Markdown-исходников документации]]=== |
| | |
| ===[[Фиксация изменений и отправка в удаленный репозиторий GitLab|3. Фиксация изменений и отправка в удаленный репозиторий GitLab]]=== | | ===[[Фиксация изменений и отправка в удаленный репозиторий GitLab|3. Фиксация изменений и отправка в удаленный репозиторий GitLab]]=== |
| | |
| ===[[Проверка и утверждение изменений в Merge Request|4. Проверка и утверждение изменений в Merge Request]]=== | | ===[[Проверка и утверждение изменений в Merge Request|4. Проверка и утверждение изменений в Merge Request]]=== |
| ===[[Автоматическая генерация HTML-страниц и обновление сайта|5. Автоматическая генерация HTML-страниц и обновление сайта]]===
| |
|
| |
| ==Фиксация изменений и отправка в удаленный репозиторий GitLab==
| |
| Для контроля вносимых в документацию изменений и их публикации на gitlab используется система контроля версий GIT
| |
|
| |
| Перед началом работы с GIT необходимо его установить на компьютер и склонировать репозиторий (см. п. 1.2)
| |
|
| |
| Алгоритм работы с GIT следующий:
| |
|
| |
| Создаётся отдельная ветка, в которой будет работать только один разработчик документации
| |
| Если работа производится в уже существующей ветке, то подгружается актуальная документация из удалённого репозитория в ветку main из которой добавляются изменения, внесённые другими пользователями, в текущую рабочую ветку
| |
| Изменения в документации подготавливаются к фиксации - все, либо выборочно (добавляются в индекс)
| |
| Изменения фиксируются (делается коммит) с кратким описанием
| |
| Зафиксированные изменения публикуются на gitlab
| |
| 3.1 Создание отдельной ветки
| |
| В GIT новую ветку можно создать из любой другой, но в данной инструкции рассмотрен случай, когда все ветки создаются из одной главной - main.
| |
|
| |
| В нижнем левом углу выберите ветку (по умолчанию это обычно main или master).
| |
| Нажмите на название ветки и выберите Создать новую ветвь.
| |
|
| |
| 20
| |
|
| |
| Введите название новой ветки и подтвердите создание, нажав Enter.
| |
| После подтверждения создания ветки произойдёт автоматическое переключение на неё. В новой ветке будут все изменения (коммиты) ветки, из которой она создавалась
| |
|
| |
| 21
| |
|
| |
| 3.1.1 Работа с существующей веткой
| |
| Если необходимо внести изменения в уже существующую ветку, созданную из главной - main, сначала подгружаются все актуальные изменения из main, текущая ветка сливается с main решаются конфликты (если возникают), и только после этого вносятся изменения в текущую рабочую ветвь. Такой алгоритм позволяет уменьшить количество конфликтов и работать с актуальной версией документации в своей ветке.
| |
|
| |
| 3.1.1.1 Подгрузка актуальных изменений
| |
| Первым делом необходимо переключиться на ветку main (предварительно зафиксировав внесённые в свою ветку изменения - см п.3.2, 3.3): В левом нижнем углу экрана нажимаем на название текущей ветки
| |
| Нажмите на название ветки и выберите main из списка вверху посередине экрана.
| |
|
| |
| 22
| |
|
| |
| Затем нажимаем на Git Graph и Fetch From Remote как показано на рисунке ниже.
| |
|
| |
| 23
| |
|
| |
| 3.1.1.2 Слияние текущей рабочей ветки с main
| |
| Переключитесь на рабочую ветку аналогично п.3.1.1.1.
| |
| Затем в разделе Git Graph найдите последний коммит ветки main вверху появившегося списка коммитов и через контекстное меню, вызванное ПКМ произведите слияние с веткой main:
| |
|
| |
| 24
| |
| 25
| |
|
| |
| 3.1.1.3 разрешение конфликтов при слиянии
| |
| В процессе слияния рабочей ветки с main могут возникнуть конфликты, в случае если в двух разных ветвях (например main и readme-develop) были зафиксированы изменения в одном и том же файле.
| |
|
| |
| При этом появится сообщение, в котором указаны файлы с конфликтующими изменениями:
| |
|
| |
| 26
| |
|
| |
| Файлы, в которых возник конфликт подсвечиваются красным цветом в проводнике.
| |
| Далее разрешаются конфликты для каждого файла после нажатия на кнопку Разрешить в редакторе слияния. GIT предложит принять изменения либо из рабочей ветки, либо из той, которая сливается с рабочей, либо принять изменения из обоих веток.
| |
| 27
| |
|
| |
| После разрешения всех конфликтов производится фиксация изменений (коммит), см. п.3.2, 3.3
| |
|
| |
| 3.2 Подготовка изменений к фиксации
| |
| После внесения изменений в документы, откройте вкладку "Система управления версиями" (значок с тремя точками и линиями). Здесь располагается список изменённых файлов. Чтобы добавить изменения в индекс, нужно нажать знак «+» рядом с каждым файлом (или напротив "Изменения", чтобы добавить все файлы сразу).
| |
|
| |
| 28
| |
|
| |
| 3.3 Создание коммита
| |
| После добавления изменений в индекс в поле ввода "Сообщение" вверху вкладки "Система управления версиями" пишется краткое описание изменений (например, "Добавлена глава..."). Нажмите на синюю кнопку "Фиксация" для фиксации изменений (коммит).
| |
|
| |
| 29
| |
|
| |
| 3.4 Публикация изменений на GitLab
| |
| После создания коммита нажмите на кнопку "Опубликовать ветку" если рабочая ветка ранее не публиковалась на gitlab или "Синхронизировать изменения", чтобы загрузить изменения в существующую ветку
| |
| Эта кнопка отправит изменения на удалённый репозиторий GitLab.
| |
|
| |
| 30
| |
|
| |
| 31
| |
|
| |
| ==Проверка и утверждение изменений в Merge Request==
| |
| Если внесённые изменения находятся в отдельной ветке GIT, они должны быть добавлены в одну единственную, главную ветку (обычно main), в которой находится вся остальная документация.
| |
|
| |
| Для этого необходимо выполнить следующее:
| |
|
| |
| Зайти на страницу с репозиторием, в данном случае https://gitlab.chemsoft.ru/chemic3-group/chemsoft-docs-content
| |
| Создать запрос на слияние (merge request) одним из двух способов:
| |
| через вкладку Merge requests в боковом меню слева
| |
| с помощью кнопки, появляющейся в верхней части окна после внесения изменений на gitlab
| |
| При первом способе после нажатия на вкладку Merge requests в разделе Code левого бокового меню происходит перенаправление на страницу, где нужно нажать на кнопку New merge request
| |
| 32 33
| |
| После этого происходит перенаправление ещё на одну страницу, где необходимо указать ветку с изменениями (Source branch - слева) и ветку для слияния (Target branch - справа), и нажать на кнопку Compare branches and continue
| |
|
| |
| 34 На следующей странице необходимо настроить запрос на слияние, а именно:
| |
|
| |
| Указать заголовок merge request
| |
| Добавить описание merge request
| |
| Назначить ответственного
| |
| Назначить проверяющего
| |
| Нажать кнопку Create merge request 36
| |
| При втором способе после нажатия кнопки Create Merge Request проделываются шаги 1-5, описанные выше.
| |
| 37
| |
|
| |
| На странице запроса на слияния происходит подтверждение слияния с веткой проверяющим нажатием на кнопку Merge При этом есть возможность для просмотреть изменения, и оставить комментарий (замечания) к запросу.
| |
|
| |
| Сообщение Ready to merge! означает что конфликты между ветками отсутствуют и они готовы к слиянию.
| |
| Если возникают конфликты, вместо этого сообщения будет соответствующее предупреждающее сообщение. В этом случае необходимо разрешить конфликты следуя пунктам 3.1.1.1, 3.1.1.2, 3.1.1.3 и опубликовать рабочую ветвь без конфликтов (п.3.3, 3.4), после чего вернуться к запросу на слияние на gitlab и убедиться в готовности к слиянию.
| |
|
| |
| Так же при слиянии существуют дополнительные действия:
| |
|
| |
| Delete source branch - удаление рабочей ветки
| |
| Squash commits - Объединение коммитов в один
| |
| Edit commit message - Редактирование сообщения к коммиту
| |
| 38
| |
|
| |
| ==Автоматическая генерация HTML-страниц и обновление сайта==
| |
| После подтверждения merge request автоматически генерируется пакет с WEB страницами, включающие все последние изменения репозитория и публикует по адресам:
| |
|
| |
| https://astra.chemsoft.ru/doc
| |
| https://triteia.chemsoft.ru/doc
| |
|
| |
| Пример сформированного документа:
| |
|
| |
| 1
| |
|
| |
| Справочник состоит из оглавления в левой части интерфейса, и контента справа, отображающего содержимое выбранной главы.
| |
|
| |
|
| Для удобства работы пользователя доступны функции навигации, поиска и смены цветовой темы.
| | ===[[Автоматическая генерация HTML-страниц и обновление сайта|5. Автоматическая генерация HTML-страниц и обновление стендов]]=== |
