From bed6f93626024b57b3e2d122c057a9cc458a1957 Mon Sep 17 00:00:00 2001 From: Andriy Oblivantsev Date: Fri, 10 Jul 2026 10:56:13 +0100 Subject: [PATCH] docs: default caveman style for issues, PRs, and reviews Document caveman-full as the collaboration voice in AGENTS and CONTRIBUTING, and add Gitea issue/PR templates that pre-fill terse structure. --- .github/ISSUE_TEMPLATE/config.yml | 8 +++++++ .github/ISSUE_TEMPLATE/default.md | 24 +++++++++++++++++++++ .github/pull_request_template.md | 19 +++++++++++++++++ AGENTS.md | 17 +++++++++++++++ CONTRIBUTING.md | 35 +++++++++++++++++++++++++++++++ docs/improvement/README.md | 7 +++++++ 6 files changed, 110 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/default.md create mode 100644 .github/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..aeca6a8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Design docs + url: https://git.produktor.io/eSlider/swarm-house/src/branch/main/docs/12-design-journey.md + about: Start with the design journey, then open an issue here. + - name: Open questions + url: https://git.produktor.io/eSlider/swarm-house/src/branch/main/docs/09-open-questions.md + about: Known unknowns — check before duplicating. diff --git a/.github/ISSUE_TEMPLATE/default.md b/.github/ISSUE_TEMPLATE/default.md new file mode 100644 index 0000000..0b6b8fe --- /dev/null +++ b/.github/ISSUE_TEMPLATE/default.md @@ -0,0 +1,24 @@ +--- +name: Change / task +about: Default issue template — caveman style +title: "" +labels: [] +--- + +Write **caveman-full**: short lines, fragments OK, no filler. See [`CONTRIBUTING.md`](../../CONTRIBUTING.md#caveman-style-default). + +## What + + + +## Why + + + +## Done when + +- [ ] + +## Notes + + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..fb2857d --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,19 @@ +Write **caveman-full** by default. See [`CONTRIBUTING.md`](../CONTRIBUTING.md#caveman-style-default). + +## What + + + +## Why + + + +## Test + +- [ ] `pytest tests/ -q` (if code touched) +- [ ] `python scripts/check_docs.py` (if docs touched) +- [ ] ADR added if boundary/contract changed + +## Links + + diff --git a/AGENTS.md b/AGENTS.md index f110b52..2c6e9b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,6 +24,23 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow and TDD re ## Conventions +### Caveman style (default for collaboration) + +**Issues, pull requests, and code reviews** use **caveman-full** by default: + +- Short sentences or fragments; drop articles and filler when clear +- Lead with fact, verdict, or ask — not preamble +- Bullets over paragraphs; one idea per line +- Keep technical terms, acronyms, paths, and code exact +- English only; no identifying references (same as all repo prose) + +README tiers: root [`README.md`](README.md) = **caveman-lite** (full sentences, less filler); +component READMEs = **caveman-full**. Design docs in `docs/` stay readable prose unless +editing for consistency. + +Templates: [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/), +[`.github/pull_request_template.md`](.github/pull_request_template.md). + - Markdown: ATX headings, fenced code blocks with language tags, pipe tables. - Python: PEP 8, type hints, pure functions where possible, no unnecessary classes. - TypeScript: strict mode, functional components and hooks, no extra UI libraries. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd12c7b..6a5b35b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,6 +77,41 @@ test: cover broadcast frame roundtrip Never include AI tool references, `Co-authored-by` trailers for assistants, or identifying names of people, companies, or locations. +## Caveman style (default) + +Use **caveman-full** in **issues**, **pull requests**, and **reviews** unless the +author explicitly asks otherwise. + +| Do | Skip | +| --- | --- | +| Short lines, fragments OK | Long preamble ("I wanted to start by saying…") | +| Lead with what / why / verdict | Filler ("just", "basically", "kind of") | +| Bullets, checklists | Repeated context already in diff or issue | +| Exact terms, paths, code | Invented abbreviations or vague "the thing" | + +**Examples** + +| Fluffy | Caveman | +| --- | --- | +| I think we should probably consider adding a link checker to CI because links might break. | Add CI link checker. Broken relative links fail merge. | +| This pull request implements the documentation improvements that were discussed in the audit. | Docs audit: glossary T0–T4, fix ground README link, rsync wording. | +| LGTM but maybe we could think about whether the anchor format is consistent? | Merge OK. Fix glossary anchors in follow-up (#1). | + +README intensity: root = caveman-lite; `simulator/`, `prototype/`, `infra/`, `docs/adr/` READMEs = +caveman-full. Numbered design docs in `docs/` stay full prose. + +Gitea pre-fills [issue](.github/ISSUE_TEMPLATE/default.md) and +[PR](.github/pull_request_template.md) templates with this style. + +### Reviews + +Default review voice = caveman-full: + +1. **Verdict first** — merge / wait / no, or approve / request changes +2. **Findings** — bullet per blocker or nit; file + line when useful +3. **Scope** — say if issue AC met, partial, or out of scope +4. No essay; link ADR, issue, or doc section instead of restating design + ## Pull request checklist - [ ] Tests added or updated; `pytest tests/ -q` passes locally diff --git a/docs/improvement/README.md b/docs/improvement/README.md index 69596cc..cfef87f 100644 --- a/docs/improvement/README.md +++ b/docs/improvement/README.md @@ -6,6 +6,13 @@ Point-in-time audits and follow-up work for links, terminology, readability, and | --- | --- | --- | | [2026-07-10 audit](2026-07-10-audit.md) | 2026-07-10 | Full `docs/` + README pass; glossary T0–T4; live demo links | +## Collaboration style + +Issues, PRs, and reviews default to **caveman-full** ([`CONTRIBUTING.md`](../../CONTRIBUTING.md#caveman-style-default), +[`AGENTS.md`](../../AGENTS.md#caveman-style-default-for-collaboration)). Gitea templates live under +[`.github/ISSUE_TEMPLATE/`](../../.github/ISSUE_TEMPLATE/) and +[`.github/pull_request_template.md`](../../.github/pull_request_template.md). + ## CI automation Enforced in Gitea Actions (`docs-verify` job). Rules live in [`scripts/docs_rules.yaml`](../../scripts/docs_rules.yaml); see [ci-rules.md](ci-rules.md).