fox/CONTRIBUTING.md

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

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

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 командой:

   npm install
   

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

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

   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 должен выглядеть так:

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) в репозиторий. В появивщемся окне введите свое имя пользователя и токен доступа.