Contribution guides

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!`.
+- Коммит должен содержать законченную функциональность.<br>
+  Модуль должен сохранять рабочее состояние в рамках каждого коммита (не только в рамках всего пулл реквеста).
+- Коммит должен содержать единственную функциональность.<br>
+  Если пулл реквест модифицирует несколько функциональностей, они должны быть разбиты на отдельные коммиты.
+- При исправлении замечаний к пулл реквесту **contributor** создает дополнительный коммиты с префиксом `fixup!` и указание sha исправляемого коммита.
+
+## Оформление пулл реквеста 
+
+**Contributor** при оформлении пулл реквеста должен учесть следующие требования:
+
+- Название пулл реквеста должно отражать суть вносимых изменений.<br>
+  В случае если пулл реквест состоит из одного коммита - название пулл реквеста это имя коммита без conventional префикса. 
+- В пулл реквесте присутствует дополнительное объяснение вносимых изменений.<br>
+  В случае исправления ошибки - ссылка на соответствующий issue или описание ошибки.<br>
+  В случае добавления функциональности - описание функциональности, ссылка на связанный коммит в документацию.<br>
+  В случае визуальных изменений скриншот или видео до/после.
+- После того, как maintainer принимает пулл реквест, в случае, если были созданы коммиты с префиксов `fixup!`, необходимо провести ручной rebase с флагом `--autosquash`, чтобы объединить исправления в оригинальные коммиты.

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
+
+
+

ru/dev/metapackage.md

@@ -0,0 +1,10 @@
+# Метапакет
+
+Метапакет - это один из способов упрощения модульной разработки проектов.
+
+Процесс разработки в метапакете несколько отличается от более популярного подхода с "монорепозиторием".
+
+Принципиальное отличие - каждый модуль внутри метапакета содержит независимую инфраструктуру.
+Сам метапакет лишь добавляет дополнительный слой инфраструктуры для улучшения опыта разработки в модульной системе.
+
+Монорепа напротив имеет общую инфраструктуру. Модули внутри монорепы не могут быть собраны снаружи от нее. 

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).

ru/toc.yaml

@@ -1,5 +1,3 @@
-title: Diplodoc
-href: index.yaml
 analytics:
   text: 'Мы используем <a href="https://yandex.ru/legal/cookies_policy">файлы cookie</a>, чтобы вы могли наилучшим образом пользоваться нашим веб-сайтом. Если вы продолжаете использовать наш веб-сайт, мы полагаем, что вы согласны с таким использованием.'
   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
+    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