KsaiLabKsaiLab
10 Development Workflow

Development Workflow

Development Workflow

Зачем нужен этот раздел

Этот раздел фиксирует единый flow разработки для frontend-ksailab, backend-ksailab, Keycloak-контура и docs-ksailab.

Цель — сделать delivery-прозрачным, трассируемым и воспроизводимым:

  • каждая работа начинается с issue;
  • критичные изменения сначала получают test design;
  • код, конфигурация и документация обновляются в одном цикле;
  • changelog и devlog позволяют восстановить историю решений и связных коммитов.

Целевой flow

Стандартный путь задачи:

  1. Issue
  2. Test design
  3. Feature branch
  4. Implementation
  5. Docs sync
  6. DEVLOG / CHANGELOG
  7. Merge Request

Для auth, permissions, provisioning, onboarding, ABAC и Keycloak changes этот порядок считается обязательным.

Issue-first модель

Рабочие задачи ведутся через единый GitLab board.

Канонический GitLab-инстанс для KSAILab: https://gitlab.fxserver.ru/. Канонический Codex MCP alias для работы с ним: gitlab-fxserver. Текущая рабочая интеграция реализована через @zereight/mcp-gitlab и GitLab REST API https://gitlab.fxserver.ru/api/v4.

Каждая issue должна содержать:

  • цель;
  • affected repos;
  • acceptance criteria;
  • required tests;
  • required docs updates;
  • rollout notes, если меняется auth или infra.

Рекомендуемые label-группы:

  • repo::frontend
  • repo::backend
  • repo::keycloak
  • repo::docs
  • area::auth
  • area::permissions
  • area::provisioning
  • area::abac
  • type::feature
  • type::bug
  • type::docs

Git flow

Стандарт для всех репозиториев:

  • feature branch + merge request

Branch naming:

  • feat/<issue-id>-short-name
  • fix/<issue-id>-short-name
  • docs/<issue-id>-short-name
  • chore/<issue-id>-short-name

Прямые коммиты в main/master не считаются нормой.

Test-first для критичных зон

Backend

В backend-ksailab уже есть test stack на pytest.

Для критичных изменений обязательны:

  • unit tests;
  • integration tests;
  • при необходимости e2e/smoke checks.

Минимальные quality gates:

  • pytest
  • ruff check .
  • black --check .

Frontend

В frontend-ksailab test stack ещё нужно formalize.

Базовая целевая пирамида:

  • Vitest для composables, services и permission logic;
  • Vue Test Utils для UI logic;
  • Playwright для auth/onboarding critical flows.

До её полного внедрения в процесс всё равно нужно заранее фиксировать expected tests в issue и MR.

Keycloak

Для Keycloak-контура validation evidence теперь разделяется по repo responsibility:

  • в keycloak-scripts-ksailab branch/MR validation трактуется как Python-only scripts validation;
  • bootstrap/import validation и provisioning smoke для scripts repo идут через shared CI;
  • физические deployment checks для Keycloak относятся к infra-keycloak-ksailab;
  • theme build/verification относится к keycloak-theme-ksailab.

CI source of truth для scripts/theme pipelines живёт в ci-pipelines/pipelines-ksailab. Локальный .gitlab-ci.yml в scripts repo должен восприниматься как include-only точка подключения, а не как место для самостоятельной CI-логики. Shared template больше не содержит validate-powershell, поэтому branch/MR validation для keycloak-scripts-ksailab нужно трактовать как Python-only.

Changelog и DEVLOG

CHANGELOG

frontend, backend и keycloak должны вести CHANGELOG.md в release-oriented формате.

Подходит модель Keep a Changelog:

  • Added
  • Changed
  • Fixed
  • Removed
  • Security

DEVLOG

Каждый repo ведёт DEVLOG.md как текущий рабочий журнал.

Запись должна включать:

  • дату;
  • issue;
  • summary;
  • tests;
  • docs;
  • links to related commits/MR.

Что должно быть в merge request

Каждый MR обязан содержать:

  • ссылку на issue;
  • summary изменений;
  • test evidence;
  • docs update notes;
  • changelog/devlog confirmation;
  • rollout notes для auth/infra work.

Для auth, permissions, provisioning и Keycloak MR без тестов и docs sync считается неполным.

Порядок merge request для auth-wave

Для authorization, onboarding и Keycloak migration work принимается такой порядок:

  1. Сначала обновляется docs-ksailab как source of truth.
  2. На docs-ветку открывается отдельный MR с архитектурной и process-синхронизацией.
  3. Затем открываются отдельные MR по backend-ksailab, frontend-ksailab и нужным Keycloak repo (keycloak-scripts-ksailab, infra-keycloak-ksailab, keycloak-theme-ksailab), если этот слой реально затронут.
  4. Каждый code/infrastructure MR ссылается на docs MR и на свой issue.

Это нужно, чтобы код не опирался на "устную" архитектуру и чтобы reviewers видели зафиксированные контракты до merge реализации.

Когда можно начинать код

Для auth/provisioning/ABAC wave команда считается готовой к реализации, когда одновременно выполнены такие условия:

  1. Есть связанные issue в docs, backend, frontend и в релевантном Keycloak repo.
  2. В issue уже зафиксирован test design для критичных изменений.
  3. В docs-ksailab обновлены целевые разделы по auth, provisioning, frontend surface и workflow.
  4. Есть рабочие feature/docs branches под каждый слой.
  5. Понятно, какие части делаем как code/config, а какие допустимы только как временная диагностика.

После этого можно начинать параллельно:

  • backend-код;
  • frontend-код;
  • keycloak-scripts-ksailab bootstrap/config;
  • при необходимости infra-keycloak-ksailab deployment changes;
  • при необходимости keycloak-theme-ksailab theme changes;
  • точечную проверку гипотез через Keycloak GUI, если она сразу синхронизируется обратно в репозиторий.

Правило для временного Keycloak GUI

Работа через Keycloak GUI допустима только как временный operational инструмент:

  • для smoke-проверки realm/client setup;
  • для диагностики и поиска корректных значений;
  • для аварийного unblock, если as-code путь временно недоступен.

Но GUI не считается source of truth. Любая рабочая правка, сделанная через GUI, должна в том же delivery cycle быть:

  • перенесена в keycloak-scripts-ksailab;
  • перенесена в keycloak-scripts-ksailab;
  • упомянута в issue/MR;
  • отражена в docs, если она влияет на архитектуру или operating model.

Репозиторные правила

Во всех основных репозиториях должны существовать:

  • AGENTS.md
  • CONTRIBUTING.md
  • DEVLOG.md
  • GitLab issue templates
  • GitLab MR template

Это делает процесс одинаково понятным для людей и для агентов.

Агентный слой

Для подготовки корректных GitLab issues и MR drafts допускается использовать локальный Codex skill gitlab-delivery-flow.

Он не заменяет issue templates и repo rules, а опирается на них:

  • читает AGENTS.md и CONTRIBUTING.md;
  • использует .gitlab templates;
  • помогает не пропускать tests, docs sync и changelog/devlog requirements.

Подробная схема подключения к GitLab MCP, текущий Codex setup и operating rules зафиксированы в отдельном документе: gitlab-instance-and-mcp.md.

Frontend Platform

GitLab Instance And MCP