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