fox/CONTRIBUTING.md

Как внести изменения в документацию

Процесс внесения изменения в документацию состоит из шагов:

1. Создать ветку, в которой добавить новый контент или изменить существующий.
2. Создать запрос на слияние вашей ветки.
3. Запросить ревью изменений.
4. После согласования новой версии выполняется слияние вашей ветки с веткой main и релиз документации.

Слияние вашей ветки с веткой main и релиз документации выполняет ответственный за портал документации.

Важно. Название ветки должно начинаться с префикса feature/. Это необходимо для публикации MR на тестовом стенде для проведения ревью.

1. Перейдите в git-репозитории https://git.vimpelcom.ru/common/vega/beecloud-docs
2. Создайте отдельную ветку для внесения изменений:
   • в навигации перейдите в раздел </> Сode → Branches;
   • нажмите New branch;
   • заполните Branch name: feature/<имя ветки>;
   • выберите ветку-источник Create from: develop;
   • нажмите Create branch.
3. Перейдите в редактор md-файлов и внесите изменения в документацию. Рекомендуется использовать встроенный редактор Gitlab WEB Ide:
   • на странице вашей ветки нажмите Edit → WEB Ide;
   • редактор WEB Ide откроется в отдельной странице;
   • выберите раздел документации и внесите изменения;
   • сохраните изменения.
4. Отправьте изменения в репозиторий:
   • в WEB Ide перейдите раздел Source Control;
   • нажмите Commit to название ветки>;
   • нажмите Create MR в правом нижнем углу;
   • будет создан запрос на слияние и откроется страница New merge request;
   • укажите ревьюера, можно добавить несколько ревьюеров;
   • укажите метку Рецензия;
   • нажмите 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 командой:

   npm install
   

   Данный шаг выполняется единожды, чтобы установить npm в репозитории для запуска сборки портала документации.

5. Запустите сборку документации командой в терминале:

   npm run dev
   

6. В результате выполнения команды сформирована ссылка на портал документации вида: http://localhost:5173/docs/. Откройте ссылку в браузере для просмотра портала документации. Ссылка будет доступна только с вашего компьютера.

Вопросы и ответы

Не устанавливается npm

Если при выполнении команды npm install не проходит проверка сертификатов, то выполните следующее:

1. В файл .npmr c самой первой строчкой добавить cafile=VimpelcomCAG2.pem. Файл .npmr должен выглядеть так:

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.