Proces wytwórczy normy

Zespół dyscypliny projektuje normę, pisze skrypt weryfikujący i publikuje wersjonowaną dyscyplinę na portalu. Każda norma jest samodzielną kapsułką z opisem wymagań i automatyczną logiką pomiaru.

flowchart LR
    A(["① Zespół\ndyscypliny"])
    A -->|opisuje wymagania| B["README.md\nSTD-XXX-YYY"]
    A -->|pisze / zleca| C["bin/checks.sh\nskrypt weryfikujący"]
    B --> D["Merge Request\ndo main"]
    C --> D

    D --> E(["② Centralny\nCI Pipeline"])
    E -->|git tag vX.Y.Z| F["Nowa wersja\ndyscypliny"]
    F -->|publikacja| G["Portal\nGitLab Pages"]

    style A fill:#1a3a5c,color:#fff
    style E fill:#1a3a5c,color:#fff
    style G fill:#3949ab,color:#fff,stroke:#3949ab

① Tworzenie normy

• Zespół dyscypliny otwiera MR z nowym folderem standards/{domena}/STD-XXX-YYY/. Identyfikator jest trwały — raz nadany nie zmienia się nawet po wycofaniu normy.

• W README.md wymagania są zapisywane w języku BCP 14 (MUSI / POWINIEN / MOŻE). Sekcja §3 MUSI być niezależna od narzędzi — opinie o konkretnych rozwiązaniach trafiają wyłącznie do §5 (Implementacja).

• Każde wymaganie normatywne dostaje definicję w sekcji 4. Minimum of Done: typ weryfikacji (auto / manual / attestation), tier środowiskowy (test / preprod / prod) i metodę pomiaru.

② Skrypt weryfikujący

• Dla checków type: auto zespół pisze bin/checks.sh. Skrypt używa exit 0 dla pass i exit 1 dla fail. MUSI być idempotentny — wielokrotne uruchomienie daje ten sam wynik.

• Checki type: api odpytują GitLab API ($GITLAB_TOKEN, $CI_API_V4_URL) — np. sprawdzają ochronę brancha main.

• Checki type: attestation odczytują klucz z discipline.yaml (spec.attest.*). Brak klucza = fail = jawny dług techniczny.

• Weryfikacja manualna (type: manual) nie ma skryptu — wymaga atestacji w discipline.yaml.

③ Przegląd i publikacja

• MR przechodzi przez recenzję. Nowy check obowiązkowy (conformance: mandatory) na tierze test lub preprod to zmiana minor semver — aplikacje muszą się dostosować lub zgłosić waiver. Zmiana formatu discipline.yaml lub usunięcie normy to zmiana major.

• Po merge'u na main zespół tworzy tag vX.Y.Z. Tag wyzwala centralny CI Pipeline, który buduje dokumentację i publikuje ją na GitLab Pages wraz z aktualną wersją dyscypliny.

• Od tego momentu aplikacje mogą zaktualizować pin w discipline.yaml:

spec:
  discipline:
    ref: X.Y.Z

Note

Kluczowe rozróżnienie:

• Norma (README.md + bin/checks.sh) jest prawem — opisuje co MUSI być spełnione.
• Skrypt jest pomiarem — sprawdza czy prawo jest przestrzegane.

Zmiana prawa bez aktualizacji pomiaru to martwa norma.

---