Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
191 lines (129 loc) · 5.49 KB

CONTRIBUTING.md

File metadata and controls

191 lines (129 loc) · 5.49 KB
Raw

Přispívání do repozitáře

Děkujeme za zájem o přispění do dokumentace AMČR API.
Níže jsou popsány pracovní postupy pro přispěvatele.

Větve (branches)

Větev Účel
main Jediná větev — publikovaná dokumentace na api.aiscr.cz; všechny PR cílí do main

Poznámka: Repozitář používá single-branch workflow — pull requesty se otevírají vždy do main. Nikdy nepushujte přímo do main bez PR.

Konvence pojmenování větví

<typ>/<popis-v-kebab-case>

Příklady:

docs/aktualizace-oai-pmh-endpointu
fix/oprava-auth-api-prikladu
chore/aktualizace-fontawesome-extension
ci/oprava-deploy-workflow
agents/claude/review-api-sections
agents/copilot/update-changelogs

Větve pro AI agenty

AI-generované větve musí dodržovat konvenci:

agents/<jmeno-agenta>/<tema>

Příklady:

agents/claude/review-oai-pmh
agents/claude-code/update-cicd-analysis
agents/copilot/fix-endpoint-examples

Větve agentů vždy cílí na main přes PR — nikdy přímý push.

Typy příspěvků

docs:    Nový nebo aktualizovaný obsah dokumentace API
fix:     Oprava chyby (nesprávné endpointy, překlepy, rozbité příklady)
style:   Změny stylů (SCSS/CSS), bez změn obsahu
chore:   Údržba projektu (aktualizace Quarto, extensions, závislostí)
ci:      Změny GitHub Actions workflows

Pull Request proces

  1. Vytvořte větev z main
  2. Proveďte změny v .qmd souborech nebo konfiguračních souborech
  3. Lokálně sestavte dokumentaci: quarto render
  4. Zkontrolujte výstup v _site/ — ověřte, že se stránky správně generují
  5. Ověřte správnost dokumentovaných endpointů vůči živým API nebo zdrojovému kódu backendů (OAI-PMH: api.aiscr.cz/oai; File API: digiarchiv.aiscr.cz; Auth API: amcr.aiscr.cz — api.aiscr.cz je jen dokumentace). Viz AGENTS.md — Verification Sources.
  6. Otevřete PR do main s popisem změn
  7. Počkejte na review od vlastníků (viz soubor CODEOWNERS v kořeni repozitáře)
  8. Po schválení bude PR mergován

Co kontrolovat před odesláním PR

  • quarto render proběhne bez chyb
  • Nové obrázky jsou uloženy do figs/
  • Nové stránky jsou zahrnuty v _quarto.yml
  • Dokumentované API endpointy odpovídají skutečnosti — ověřit vůči live API nebo zdrojovému kódu
  • Příklady kódu (curl) jsou funkční
  • Changelog v changelogs/ je aktualizován při změně popisu endpointů

Commit messages

Formát:

<typ>: <stručný popis v češtině nebo angličtině>

Příklady:

docs: aktualizace popisu OAI-PMH ListRecords endpoint
fix: oprava příkladu Auth API token requestu
chore: upgrade quarto-ext/fontawesome na v1.1.0
ci: přidat validaci odkazů do deploy workflow

Quarto specifika

Freeze

Repozitář používá _freeze/ pro reproducibilitu výpočtů.
Freeze soubory jsou verzovány v Gitu — při změně výpočetního kódu spusťte:

quarto render --execute

Extensions

Quarto extensions jsou uloženy v _extensions/.
Pro aktualizaci:

quarto add quarto-ext/fontawesome

Lua filtry

Repozitář obsahuje Lua filtry. Při úpravách Lua kódu otestujte render výstup.

Přesnost dokumentace API

Kritické: Dokumentace API musí vždy přesně odrážet chování živého API.

Při úpravě popisu endpointů nebo parametrů vždy ověřte vůči:

Podrobně viz AGENTS.md — Verification Sources.

Dokumentace a vlastnictví pravidel

  • AGENTS.md — vlastní pravidla pro AI agenty, rozsah změn, zdroje pro ověřování API, struktura .agents/.
  • CONTRIBUTING.md — vlastní pracovní postup přispěvatelů (větve, PR, commity, Quarto).
  • Ostatní soubory (CLAUDE.md, .cursor/rules, …) pouze odkazují na tyto zdroje; pravidla se nekopírují.

AI-asistované přispívání

Větve vytvořené AI agenty musí:

  1. Dodržovat konvenci pojmenování agents/<jmeno-agenta>/<tema>
  2. Cílit výhradně na větev main přes PR
  3. Obsahovat v popisu PR jasné označení, že jde o AI-generovaný obsah
  4. Projít standardním code review — změny v .agents/ vyžadují lidský review

Jak spustit review session

Otevřete nový kontext AI agenta a jako první zprávu vložte:

Přečti .agents/prompts/review_codebase.md a spusť review session.

Agent si načte AGENTS.md, kontext z .agents/ a zahájí session dle instrukcí v .agents/prompts/review_codebase.md. Typy sezení (general-review, oai-pmh-accuracy, file-api-accuracy, auth-api-accuracy aj.) jsou popsány tamtéž.

Hlášení problémů

Chyby a návrhy hlašte prostřednictvím GitHub Issues
nebo GitHub Discussions.

U issues uveďte:

  • URL stránky nebo název endpointu, které se problém týká
  • Popis problému (dokumentované chování vs. skutečné chování)
  • Případný curl příkaz a výstup prokazující chybu