Онбординг для писаталей VK PH¶

Содержание¶

1. Стенды продукта
2. Две сети VPN
3. Репозиторий в Git
4. Процесс в Jira
5. Проект документации
6. База знаний по наработкам коллег

Стенды продукта¶

Prod¶

Прод: people-hub.ru

Для доступа к проду получите логи и пароль у руководителя. Эти логи и пароль используются исключительно для доступа к этому порталу.

Документация на проде (people-hub.ru/documentation/) опубликована в открытом доступе. Логин и пароль не нужны.

Dev¶

Дев: develop.k8s.digital-insider.ru

Для доступа к дев:

1. Настройте People Hub VPN.
2. Получите у команды разработки логины и пароли для дев-портала с ролью superuser.

Для доступа к документации в дев develop.k8s.digital-insider.ru/documentation/ достаточно подключиться через dev8 VPN.

Обновление документации публикуется в dev, когда ветка задачи вливается в ветку develop.

Две сети VPN¶

Для полноценной работы необходимо настроить две сети VPN:

1. Сеть People Hub VPN для доступа к dev.
2. Корпоративная сеть barbos VPN для доступа к корпоративным ресурсам VK, таким как Jira и Confluence.

Настройка dev8 VPN¶

См. инструкции в Confluence (необходим доступ в barbos VPN): https://confluence.vk.team/display/B2BCOR/VPN+-+People+Hub

Репозиторий в Git¶

Репозиторий документации: https://gitlab.digital-insider.ru/di/documentation

Чтобы получить доступ к репозиторию, обратитесь к старшему DevOps-инженеру команды разработки VKPH.

Пайплайны документации¶

Техпис имеет дело с единственным пайплайном: когда ветка вливается в develop, документация разворачивается в dev.

Регламент работы в Git¶

Коммиты в develop отключены. Чтобы закоммитить изменения в проект документации:

1. Сохраните свои изменения в ветке по номеру задачи, например, B2BCORE-6837.
2. Залейте ветку в репозиторий.
3. Создайте Merge Request.
4. Убедитесь, что пайплайн работает корректно.
5. При необходимости запросите ревью или получите утверждение.
6. Влейте свою ветку в develop.

Ваши изменения будут опубликованы в https://develop.k8s.digital-insider.ru/documentation/

Работа со своей веткой¶

Вы приступаете к работе над новой задачей:

$ git checkout develop
$ git pull
$ git branch B2BCORE-...
$ git checkout B2BCORE-...
...
$ git add .
$ git commit -m "B2BCORE-...: ..."
$ git checkout develop
$ git pull
$ git checkout B2BCORE-...
$ git merge develop
$ git push origin B2BCORE-...

Работа с чужой веткой¶

Вы хотите внести изменения в ветке, назначенной вам на утверждение в МР:

git checkout -b B2BCORE-... origin/B2BCORE-...
...
$ git add .
$ git commit -m "B2BCORE-...: ..."
$ git checkout develop
$ git pull
$ git checkout B2BCORE-...
$ git merge develop
$ git push origin B2BCORE-...

Процесс в Jira¶

Все задачи по документации VKPH создаются с типом Документация в проекте B2BCORE. Все такие задачи представлены на доске: https://jira.vk.team/secure/RapidBoard.jspa?rapidView=7211

По мере возможности придерживайтесь правила один документ = одна задача: если задача требует изменения нескольких документов, разбейте ее на подзадачи.

Статусная модель¶

Проект документации¶

Документация собирается движком Mkdocs или в Докере.

Чтобы проверять форматирование в реальном времени, используйте локальную сборку Mkdocs или в Докер-контейнере.

Пайплайн собирает Докер-контейнер. Этот вариант сборки полностью аналогичен стэндам.

Локальная сборка Mkdocs в Windows¶

Чтобы собирать документацию движком Mkdocs, необходимо изменить пути в mkdocs.yaml. Для этого создайте локальную копию mkdocs.yaml, которая не трекается в Git:

1. Перейдите на уровень выше папки проекта.
2. Создайте копию файла mkdocs.yaml.
3. Измените путь к папке docs:

   $ docs_dir: /app/docs
   

   на

   $ docs_dir: .\documentation\docs
   

4. Сохраните mkdocs_loc.yaml.
5. Соберите сайт:

   $ mkdocs build --config-file .\mkdocs_loc.yaml --no-directory-urls
   

   или запустите сервер:

   $ mkdocs serve --config-file .\mkdocs_loc.yaml --no-directory-urls
   

Локальная сборка в Docker-контейнере¶

Подготовка:

1. Установите Docker.
2. Получите логин и пароль к https://freeipa-01.people-hub.ru/ у старшего DevOps-инженера команды разработки VKPH.
3. Выполните команду:

   $ docker login docker.people-hub.ru
   

   и введите логин и пароль, полученные на шаге 1.
4. Выполните команду:

   $ docker login docker-tech.people-hub.ru
   

   и введите логин и пароль, полученные на шаге 1.

Чтобы развернуть локальный образ:

1. Перейдите в папку проекта.
2. Введите команды:

   $ docker-compose -f .\docker\docker-compose-local.yml build
   $ docker-compose -f .\docker\docker-compose-local.yml up
   

3. Откройте сайт по адресу http://localhost:8000/

Особенности синтаксиса md¶

Якоря¶

Добавляйте якоря ко всем заголовкам H2 (##) и H3 (###):

## \Заголовок\

Пример:

### \Внесение и изменение личной информации в профиле\

Внутренние ссылки¶

[текст ссылки](путь_и_имя_файла.md#якорь)

Пример:

Подробнее о поиске см. в разделе [Глобальный поиск](users_guide.md#title17) инструкций пользователя.

Ссылки для скачивания файлов¶

Добавьте файл в папку проекта .\docs\static.

Формат ссылки для открытия файла в браузере:

[текст ссылки](путь/static/имя_файла.ext)

Отступы в списках¶

Дополнительный отступ перед каждым следующим уровнем списка — 4 пробела:

1. уровень 1
   1. уровень 2
      1. уровень 3
   2. уровень 2
2. уровень 1

Пример:

Изображения в списках¶

Чтобы изображение соответствовало отступу уровня списка, добавьте отступы относительно начала строки элемента списка: - 4 пробела перед кодом изображения - 5 пробелов перед подписью

Пример:

Ширина изображения¶

Регулируйте ширину изображений, чтобы движок не растягивал маленькие скрины:

{ width=75% }

{ width="350px" }

Исключить документ из результатов поиска¶

В начале документа вставить:

---
search:
  exclude: true
---