Речкина Елена Валерьевна
107 lines
7.9 KiB
Markdown
107 lines
7.9 KiB
Markdown
# Как внести изменения в документацию
|
||
|
||
Процесс внесения изменений в документацию состоит из шагов:
|
||
|
||
1. Создать ветку, в которой добавить новый контент или изменить существующий.
|
||
2. Создать запрос на слияние вашей ветки.
|
||
3. Запросить ревью изменений.
|
||
4. После согласования новой версии выполняется слияние вашей ветки с веткой *main*.
|
||
5. Опубликовать новую версию документации на портале.
|
||
|
||
Слияние вашей ветки с веткой *main* и релиз документации выполняет ответственный за портал документации.
|
||
|
||
**Важно.** Название ветки должно начинаться с префикса *feature/*. Это необходимо для публикации MR на тестовом стенде для проведения ревью.
|
||
|
||
1. Перейдите в git-репозитории https://git.vimpelcom.ru/common/vega/beecloud-docs
|
||
2. Создайте отдельную ветку для внесения изменений:
|
||
- в навигации перейдите в раздел *</> Сode* → *Branches*;
|
||
- нажмите *New branch*;
|
||
- заполните *Branch name*: *feature/<имя ветки>*;
|
||
- выберите ветку-источник *Create from*: *main*;
|
||
- нажмите *Create branch*.
|
||
3. Перейдите в редактор md-файлов и внесите изменения в документацию. Рекомендуется использовать встроенный редактор *Gitlab WEB Ide*:
|
||
- на странице вашей ветки нажмите *Edit* → *WEB Ide*;
|
||
- редактор *WEB Ide* откроется в отдельной странице;
|
||
- в навигации слева в папке *src/guide* выберите существующий раздел документации, в который необходимо внести изменения; если изменения предполагают создание нового раздела в документации, то создайте новый каталог с md-файлами в в папке *src/guide*;
|
||
- внесите изменения;
|
||
- сохраните изменения.
|
||
4. Отправьте изменения в репозиторий:
|
||
- в *WEB Ide* перейдите раздел *Source Control* на панели слева;
|
||
- нажмите *Commit and push to <название ветки>*;
|
||
- нажмите *Create MR* в правом нижнем углу;
|
||
- будет создан запрос на слияние и откроется страница *New merge request*;
|
||
- введите название MR в поле *Title*;
|
||
- укажите ревьюера, можно добавить несколько ревьюеров;
|
||
- нажмите *Create merge request*.
|
||
|
||
## Как определить, в какой файл проекта вносить изменения
|
||
|
||
1. Откройте портал документации https://console.cloud.dfcloud.ru/docs/.
|
||
2. Откройте нужный раздел портале.
|
||
3. В адресной строке посмотрите название html-файла. Например, https://console.cloud.dfcloud.ru/docs/guide/compute/compute-instructions/compute-servers-create.html.
|
||
4. Перейдите в *WEB Ide* и структуре проекта найдите md-файл. Например, *compute-servers-create.html* в структуре проекта расположен по пути `guide/compute/compute-instructions/compute-servers-create.md`.
|
||
|
||
## Как опубликовать документацию
|
||
|
||
Доступна публикация портала документации локально. Публикация в интернете пока недоступна.
|
||
|
||
Требования:
|
||
|
||
- `Node.js` версии 18 и выше.
|
||
- Текстовый редактор с поддержкой синтаксиса `markdown`. Рекомендуется использовать VSCode.
|
||
|
||
1. Клонируйте репозиторий в директорию на вашем компьютере.
|
||
2. Откройте репозиторий в VSCode.
|
||
3. В VSCode откройте терминал.
|
||
4. Установите `npm` командой:
|
||
```sh
|
||
npm install
|
||
```
|
||
Данный шаг выполняется единожды, чтобы установить `npm` в репозитории для запуска сборки портала документации.
|
||
|
||
5. Запустите сборку документации командой в терминале:
|
||
```sh
|
||
npm run dev
|
||
```
|
||
6. В результате выполнения команды сформирована ссылка на портал документации вида: http://localhost:5173/docs/. Откройте ссылку в браузере для просмотра портала документации. Ссылка будет доступна только с вашего компьютера.
|
||
|
||
### Вопросы и ответы
|
||
|
||
**Нет доступа к репозиторию**
|
||
|
||
Для получения доступа к репозиторию https://git.vimpelcom.ru/common/vega/beecloud-docs напишите на почту evrechkina@beeline.ru.
|
||
|
||
**Не устанавливается `npm`**
|
||
|
||
Если при выполнении команды `npm install` не проходит проверка сертификатов, то выполните следующее:
|
||
|
||
1. В файл `.npmr` первой строкой добавить `cafile=VimpelcomCAG2.pem`. Файл `.npmr` должен выглядеть так:
|
||
|
||
```text
|
||
cafile=VimpelcomCAG2.pem
|
||
registry=https://nexus.vimpelcom.ru/repository/npm-all/
|
||
```
|
||
2. В корень репозитория положить файл сертификата `VimpelcomCAG2.pem`. Файл можно скачать: https://git.vimpelcom.ru/products/vega/frontend/-/blob/beecloud99/VimpelcomCAG2.pem?ref_type=heads.
|
||
|
||
3. Повторите установку `npm`.
|
||
|
||
**Нет доступа для отправки изменений (push) в репозиторий**
|
||
|
||
Вероятно, у вас не выпущен персональный токен доступа для выполнения операций с репозиторием.
|
||
|
||
Чтобы выпустить токен, выполните действия:
|
||
|
||
1. Войдите в свой аккаунт на платформе Git https://git.vimpelcom.ru.
|
||
2. Нажмите на иконку пользователя на панели слева.
|
||
3. Выберите **Preferences**.
|
||
4. Перейдите в раздел **Access Tokens** и нажмите **Add new token**.
|
||
5. Задайте параметры токена:
|
||
- **Token name** — имя токена;
|
||
- **Expiration date** — срок действия токена (максимум 365 дней от даты создания);
|
||
- Выберите следующий набор разрешений (scopes):
|
||
- read_repository,
|
||
- write_repository.
|
||
6. Нажмите **Create personal access token**.
|
||
7. Не закрывайте страницу с токеном. Скопируйте и сохраните созданный токен. Он отображается только один раз.
|
||
|
||
Далее перейдите в репозиторий и повторите попытку отправки своих изменений (push) в репозиторий. В появивщемся окне введите свое имя пользователя и токен доступа. |