From b3d501c9208a108c16b5e4a10a3d07d7731bcae4 Mon Sep 17 00:00:00 2001 From: "S.Gromov" Date: Fri, 1 May 2026 21:15:24 +0300 Subject: [PATCH] =?UTF-8?q?chore:=20=D0=BE=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20CI=20=D0=B4=D0=BB=D1=8F=20dev-=D0=B2=D0=B5=D1=82?= =?UTF-8?q?=D0=BA=D0=B8=20=D0=B8=20=D0=B0=D0=BA=D1=82=D1=83=D0=B0=D0=BB?= =?UTF-8?q?=D0=B8=D0=B7=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20CONTRI?= =?UTF-8?q?BUTING.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Добавлен триггер dev в CI со сборочным job (generate + docs:build + build) - Убраны устаревшие шаги: npm run docs, коммит generated/, README_RU.md - Прод-пайплайн: build → version (тег) → docker → deploy - CONTRIBUTING.md переписан под текущую структуру проекта --- .gitea/workflows/ci.yml | 57 ++++++------ CONTRIBUTING.md | 198 ++++++++++------------------------------ 2 files changed, 76 insertions(+), 179 deletions(-) diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 6e6c3d2..b1eafc5 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -2,12 +2,37 @@ name: CI/CD Pipeline on: push: - branches: [main] + branches: [main, dev] jobs: - docs: + build: runs-on: ubuntu-latest if: "!contains(github.event.head_commit.message, '[skip ci]')" + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 24 + + - name: Установка зависимостей + run: npm ci + + - name: Генерация артефактов + run: npm run generate + + - name: Сборка документации + run: npm run docs:build + + - name: Сборка лендинга + run: npm run build + + version: + runs-on: ubuntu-latest + needs: build + if: github.ref == 'refs/heads/main' && !contains(github.event.head_commit.message, '[skip ci]') outputs: version: ${{ steps.version.outputs.version }} steps: @@ -16,11 +41,6 @@ jobs: with: fetch-depth: 0 - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: 24 - - name: Версия из package.json id: version run: | @@ -28,23 +48,6 @@ jobs: echo "version=$VERSION" >> $GITHUB_OUTPUT echo "Версия: $VERSION" - - name: Генерация docs - run: | - npm ci - npm run docs - - - name: Коммит generated/ - run: | - git config user.name "CI Bot" - git config user.email "ci@gromlab.ru" - git add generated/ README_RU.md - if git diff --cached --quiet; then - echo "Нет изменений, пропуск" - else - git commit -m "docs: обновить generated (${{ steps.version.outputs.version }}) [skip ci]" - git push origin main - fi - - name: Создать тег run: | VERSION=${{ steps.version.outputs.version }} @@ -58,7 +61,7 @@ jobs: docker: runs-on: ubuntu-latest - needs: docs + needs: version if: "!contains(github.event.head_commit.message, '[skip ci]')" steps: - name: Checkout @@ -92,7 +95,7 @@ jobs: type=ref,event=branch type=sha,prefix= type=raw,value=latest,enable={{is_default_branch}} - type=raw,value=${{ needs.docs.outputs.version }} + type=raw,value=${{ needs.version.outputs.version }} - name: Build and push uses: docker/build-push-action@v5 @@ -104,7 +107,7 @@ jobs: tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} build-args: | - VERSION_TAG=${{ needs.docs.outputs.version }} + VERSION_TAG=${{ needs.version.outputs.version }} provenance: false sbom: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 136381d..0f74f06 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,182 +4,79 @@ ## О проекте -Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript. +Сайт-документация архитектуры SLM Design с лендингом. -- Движок: VitePress -- Языки: русский (основной), английский -- Русская версия: `docs/ru/` -- Английская версия: `docs/en/` +- Лендинг: React + Vite +- Документация: VitePress +- Язык: русский +- Документация: `docs/architecture/` ## Команды | Команда | Что делает | |---------|-----------| -| `npm run dev` | Локальный сервер разработки | -| `npm run build` | Сборка статического сайта | -| `npm run docs` | Генерация `generated/{lang}/RULES.md` — единый файл для AI-ассистентов | +| `npm run dev` | Локальный сервер лендинга | +| `npm run build` | Сборка лендинга | +| `npm run docs:dev` | Локальный сервер документации | +| `npm run docs:build` | Сборка документации | +| `npm run generate` | Генерация артефактов (llms.txt, llms-full.txt, ARCHITECTURE.md, ZIP, README) | ## Структура файлов ``` docs/ -├── ru/ # Русская версия (основная) -│ ├── index.md # Главная страница -│ ├── basics/ # Базовые правила -│ │ ├── tech-stack.md -│ │ ├── architecture.md -│ │ ├── code-style.md -│ │ ├── naming.md -│ │ ├── documentation.md -│ │ └── typing.md -│ └── applied/ # Прикладные разделы -│ ├── vscode.md -│ ├── project-structure.md -│ ├── components.md -│ ├── page-level.md -│ ├── templates-generation.md -│ ├── styles.md -│ ├── images-sprites.md -│ ├── svg-sprites.md -│ ├── video.md -│ ├── api.md -│ ├── stores.md -│ ├── hooks.md -│ ├── fonts.md -│ └── localization.md -├── en/ # Английская версия (зеркало ru/) +├── index.md # Страница навигации по документации +└── architecture/ # Разделы архитектуры + ├── index.md # Обзор SLM Design + ├── layers.md # Слои + ├── modules.md # Модули + └── segments.md # Сегменты .vitepress/ -├── config.ts # Конфигурация VitePress, сайдбары, локали -generated/ -├── ru/RULES.md # Сгенерированный единый файл (ru) -└── en/RULES.md # Сгенерированный единый файл (en) -concat-md.js # Скрипт генерации RULES.md +├── config.ts # Конфигурация VitePress, сайдбар +public/ +├── llms.txt # Карта документации для LLM +├── llms-full.txt # Полная документация в одном файле +└── ARCHITECTURE.md # Единый файл архитектуры +generate.ts # Скрипт генерации артефактов +src/ # Исходники лендинга (React + Vite) ``` ### Добавление нового раздела -1. Создать `.md`-файл в нужной папке (`basics/` или `applied/`). -2. Добавить пункт в сайдбар — `.vitepress/config.ts` (оба языка, если есть перевод). -3. Добавить файл в массив `fileOrder` — `concat-md.js` (для генерации RULES.md). +1. Создать `.md`-файл в `docs/architecture/`. +2. Добавить пункт в сайдбар — `.vitepress/config.ts`. +3. Добавить `description` в frontmatter файла — используется для `llms.txt`. +4. Запустить `npm run generate` для обновления артефактов. -## Два типа документации - -### Базовые правила - -**Отвечает на вопрос:** «Каким должен быть любой код?» - -Универсальные стандарты, **не привязанные к конкретной области**. -Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`. - -Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области. - -**Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых. - -### Прикладные разделы - -**Отвечает на вопрос:** «Как работать с X?» - -Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры. - -**Граница:** прикладной раздел не дублирует базовые правила. -Если правило уже описано в базовых — прикладной раздел ссылается на него, но не повторяет. - -## Структура прикладного раздела - -Шаблон ниже описывает все допустимые секции. Раздел включает только те секции, которые для него релевантны — пустые секции не создаются. - -```markdown -# {Название} - -Краткое описание: о чём раздел и какие аспекты работы с областью он охватывает. - -## Что нужно знать - -Неочевидная информация, которую читатель должен знать перед чтением раздела. -Если для раздела нет такой вводной — секция не создаётся. - -## Структура - -Файловая организация: какие файлы создавать и куда класть. -Обязательно — дерево файлов через code-block. - -## Правила - -Конкретные требования, специфичные для области. Делятся на две подсекции: - -### Реализация - -Как написан код внутри файла: синтаксис, паттерны, API. -Отвечает на вопрос: «Как писать код?» - -Примеры: объявление через `const`, деструктуризация пропсов, формат вызова `cl()`, способ подключения стилей, структура хука. - -### Организация - -Как компонент/модуль встроен в проект: файловые границы, зоны ответственности, экспорт. -Отвечает на вопрос: «Где что лежит и за что отвечает?» - -Примеры: один компонент — один файл, вложенные компоненты в `ui/`, логика выносится в `model/`. - -Формат обеих подсекций — маркированный список. -Для неочевидных случаев — блоки «Хорошо / Плохо». -Если в области нет правил одной из категорий — подсекция не создаётся. - -## Именование - -Соглашения по именам, специфичные для этой области. -Только то, что НЕ покрыто в базовом разделе «Именование». - -## Типизация - -Правила типизации, специфичные для этой области. -Только то, что НЕ покрыто в базовом разделе «Типизация». - -## Документирование - -Что и как документировать в этой области. -Только то, что НЕ покрыто в базовом разделе «Документирование». - -## Примеры - -Полноценные примеры кода. -Каждый пример с путём к файлу и пояснениями. - -``` - -### Порядок секций - -Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры. - -Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример. - -### Секции-расширения базовых правил - -«Именование», «Типизация», «Документирование» в прикладном разделе — это **точки расширения** базовых правил. - -- В базовых описано общее: `camelCase` для переменных, `type` vs `interface`, формат JSDoc. -- В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки). - -Если для области нет специфики по именованию, типизации или документированию — секция не создаётся. - -## Конвенции оформления - -### Frontmatter +## Frontmatter Каждый `.md`-файл начинается с YAML frontmatter: ```yaml --- title: Название раздела +description: Краткое описание для llms.txt --- ``` -Значение `title` совпадает с текстом `h1`-заголовка в файле. +- `title` — совпадает с `h1`-заголовком в файле. +- `description` — кратное описание содержимого страницы, используется при генерации `llms.txt`. + +## Структура страницы документации + +Каждая страница начинается одинаково: + +1. **Заголовок** (`h1`) — совпадает с `title` из frontmatter. +2. **Описание раздела** — 1–2 строки сразу после заголовка. Говорит, что это за раздел, какую информацию он описывает и что читатель в нём получит. +3. **Определение** (`## Определение`) — для справочных страниц, посвящённых одному термину. Короткая формулировка жирным: что это за сущность и какую роль она играет. +4. **Контент** — остальные `h2`-подразделы. + +## Конвенции оформления ### Заголовки - Один `h1` на файл — совпадает с `title` из frontmatter. -- Сразу после `h1` — вводный абзац (одно-два предложения). +- Сразу после `h1` — описание раздела (1–2 предложения). - Основные секции — `h2`. - Подсекции внутри `h2` — `h3`. - `h4` не используется. @@ -194,8 +91,6 @@ title: Название раздела Используются для контрастного сравнения правильного и неправильного подхода. -Формат: - ```markdown **Хорошо:** @@ -217,11 +112,10 @@ title: Название раздела ### Ссылки между разделами -Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое. +Раздел может ссылаться на другие разделы, но не дублирует их содержимое. ## Принципы 1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются. -2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное. -3. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет. -4. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён. +2. **Пустые секции не создавать.** Если для раздела нет специфики — секция не создаётся. +3. **Примеры обязательны.** Раздел без примеров кода — незавершён.