From e1ea0dc6d3dca9be06446a1741007b7d4dfb319a Mon Sep 17 00:00:00 2001
From: 3y3 <3y3@ya.ru>
Date: Thu, 21 Nov 2024 12:02:12 +0300
Subject: [PATCH] Contribution guides
---
ru/dev/contribution.md | 31 +++++++++++++++++++++++++++
ru/dev/index.yaml | 17 +++++++++++++++
ru/dev/metapackage.md | 10 +++++++++
ru/dev/quickstart.md | 48 ++++++++++++++++++++++++++++++++++++++++++
ru/toc.yaml | 16 +++++++++++---
5 files changed, 119 insertions(+), 3 deletions(-)
create mode 100644 ru/dev/contribution.md
create mode 100644 ru/dev/index.yaml
create mode 100644 ru/dev/metapackage.md
create mode 100644 ru/dev/quickstart.md
diff --git a/ru/dev/contribution.md b/ru/dev/contribution.md
new file mode 100644
index 00000000..0cac223e
--- /dev/null
+++ b/ru/dev/contribution.md
@@ -0,0 +1,31 @@
+# Внесение изменений в проект
+
+## Основной процесс
+
+В процессе внесения изменений в модуль принимает участие несколько человек:
+
+- **Contributor** - непосредственно вносит изменения.
+- **Maintainer** - отвечает за качество модуля - проводит ревью изменений, выпускает новую версию пакета.
+
+## Оформление коммитов
+
+**Contributor** при оформлении коммитов должен учесть следующие требования:
+
+- Название коммита должно соответствовать [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). Разрешенные префиксы: `chore:`, `fix:`, `feat:`, `deps:`, `fixup!`.
+- Коммит должен содержать законченную функциональность.
+ Модуль должен сохранять рабочее состояние в рамках каждого коммита (не только в рамках всего пулл реквеста).
+- Коммит должен содержать единственную функциональность.
+ Если пулл реквест модифицирует несколько функциональностей, они должны быть разбиты на отдельные коммиты.
+- При исправлении замечаний к пулл реквесту **contributor** создает дополнительный коммиты с префиксом `fixup!` и указание sha исправляемого коммита.
+
+## Оформление пулл реквеста
+
+**Contributor** при оформлении пулл реквеста должен учесть следующие требования:
+
+- Название пулл реквеста должно отражать суть вносимых изменений.
+ В случае если пулл реквест состоит из одного коммита - название пулл реквеста это имя коммита без conventional префикса.
+- В пулл реквесте присутствует дополнительное объяснение вносимых изменений.
+ В случае исправления ошибки - ссылка на соответствующий issue или описание ошибки.
+ В случае добавления функциональности - описание функциональности, ссылка на связанный коммит в документацию.
+ В случае визуальных изменений скриншот или видео до/после.
+- После того, как maintainer принимает пулл реквест, в случае, если были созданы коммиты с префиксов `fixup!`, необходимо провести ручной rebase с флагом `--autosquash`, чтобы объединить исправления в оригинальные коммиты.
\ No newline at end of file
diff --git a/ru/dev/index.yaml b/ru/dev/index.yaml
new file mode 100644
index 00000000..2e961fd3
--- /dev/null
+++ b/ru/dev/index.yaml
@@ -0,0 +1,17 @@
+title: Гайды для разработчиков платформы Diplodoc
+meta:
+ title: Метаданные
+ noIndex: true
+links:
+- title: Быстрый старт
+ description: Как быстро начать разработку с использованием Github Codespaces
+ href: quickstart.md
+- title: Внесение изменений
+ description: Правила по оформлению коммитов и пулл реквестов. Рекомендации к используемым технологиям.
+ href: contribution.md
+- title: Метапакет
+ description: Описание структуры метапакета. Нюансы работы с метапакетом.
+ href: metapackage.md
+
+
+
diff --git a/ru/dev/metapackage.md b/ru/dev/metapackage.md
new file mode 100644
index 00000000..d5930161
--- /dev/null
+++ b/ru/dev/metapackage.md
@@ -0,0 +1,10 @@
+# Метапакет
+
+Метапакет - это один из способов упрощения модульной разработки проектов.
+
+Процесс разработки в метапакете несколько отличается от более популярного подхода с "монорепозиторием".
+
+Принципиальное отличие - каждый модуль внутри метапакета содержит независимую инфраструктуру.
+Сам метапакет лишь добавляет дополнительный слой инфраструктуры для улучшения опыта разработки в модульной системе.
+
+Монорепа напротив имеет общую инфраструктуру. Модули внутри монорепы не могут быть собраны снаружи от нее.
\ No newline at end of file
diff --git a/ru/dev/quickstart.md b/ru/dev/quickstart.md
new file mode 100644
index 00000000..f358ecfa
--- /dev/null
+++ b/ru/dev/quickstart.md
@@ -0,0 +1,48 @@
+# Быстрый старт
+
+Платформа diplodoc разрабатывается на осноне набора независимых модулей, расположенных в Github организации [diplodoc-platform](https://github.com/diplodoc-platform).
+
+Каждый модуль можно разрабатывать как по отдельности, так и в составе [метапакета](./metapackage.md).
+
+Самый простой способ начать разрабатку любого модуля в системе - запустить преднастроенный GitHub Codespace в соответствующем репозитории.
+
+{% note info "" %}
+
+Подробнее про работу с GitHub Codespaces можно почитать в [официальной документации](https://docs.github.com/en/codespaces/getting-started/quickstart).
+
+{% endnote %}
+
+## Подготовка модуля
+
+После создания codespace дождитесь выполнения postCreateCommand (~3мин).
+
+На этом этапе проходит несколько подготовительных действий:
+- установка необходимых модулю NodeJS пакетов
+- предварительная сборка модуля (`npm run build`)
+- основные проверки качества кода (`npm run lint`)
+- основные тесты (`npm run test`)
+
+Когда подготовка успешно завершена, т.е. модуль собирается и проходит основные проверки - он готов к [внесению изменений](#add-changes).
+
+## Подготовка метапакета
+
+Разработка в рамках метапакета упрощает одновременное внесение изменений сразу в несколько модулей.
+
+После создания codespace дождитесь выполнения postCreateCommand (~3мин).
+
+На этом этапе проходит несколько подготовительных действий:
+- связывание git субмодулей
+- установка необходимых NodeJS пакетов в режиме npm workspaces
+- предварительная сборка графа модулей для проекта CLI (`npx nx build @diplodoc/cli`)
+
+По умолчанию при инициализации метапакета не запускаются проверки качества кода и тесты.
+Их можно запустить самостоятельно выполнив в корневой директории `npm run lint` и `npm run test` соответственно.
+При этом выполнятся соответствующие проверки во всех зависимых модулях.
+
+Когда подготовка успешно завершена, т.е. модуль собирается и проходит основные проверки - он готов к [внесению изменений](#add-changes).
+
+## Внесение изменений {add-changes}
+
+В процессе внесения изменений необходимо убедиться, что проверки качества кода (`npm run lint` и `npm run test`) в измененном модуле все еще проходят без ошибок.
+
+После этого можно приступить к [оформлению коммитов и пулл реквеста](./contribution.md).
\ No newline at end of file
diff --git a/ru/toc.yaml b/ru/toc.yaml
index e22e2b3f..91a11d56 100644
--- a/ru/toc.yaml
+++ b/ru/toc.yaml
@@ -1,5 +1,3 @@
-title: Diplodoc
-href: index.yaml
analytics:
text: 'Мы используем файлы cookie, чтобы вы могли наилучшим образом пользоваться нашим веб-сайтом. Если вы продолжаете использовать наш веб-сайт, мы полагаем, что вы согласны с таким использованием.'
buttons:
@@ -32,6 +30,9 @@ navigation:
rightItems:
- type: controls
items:
+ - name: О платформе
+ labeled: true
+ href: index.yaml
- name: Обзор системы
href: about.md
- name: Начало работы
@@ -159,4 +160,13 @@ items:
href: vacancy.md
- name: Yandex Open Source Jam 2024
hidden: true
- href: jam.md
\ No newline at end of file
+ href: jam.md
+ - name: Для разработчиков
+ labeled: true
+ href: dev/index.yaml
+ - name: Быстрый старт
+ href: dev/quickstart.md
+ - name: Внесение изменений
+ href: dev/contribution.md
+ - name: Метапакет
+ href: dev/metapackage.md