From fb548615d2a22997f97a1568d7898d90dc423ae2 Mon Sep 17 00:00:00 2001 From: jensgrote Date: Tue, 2 Jun 2026 15:15:28 +0200 Subject: [PATCH 1/2] docs: add issue title naming convention (#564) --- .github/ISSUE_TEMPLATE/contract-proposal.yml | 56 ++++++++++++++++++++ .github/ISSUE_TEMPLATE/process-proposal.yml | 53 ++++++++++++++++++ CONTRIBUTING.adoc | 46 ++++++++++++++++ CONTRIBUTING.md | 23 ++++++++ docs/CONTRIBUTING.de.adoc | 46 ++++++++++++++++ 5 files changed, 224 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/contract-proposal.yml create mode 100644 .github/ISSUE_TEMPLATE/process-proposal.yml diff --git a/.github/ISSUE_TEMPLATE/contract-proposal.yml b/.github/ISSUE_TEMPLATE/contract-proposal.yml new file mode 100644 index 00000000..df3f0672 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/contract-proposal.yml @@ -0,0 +1,56 @@ +name: 📜 Contract Proposal +description: Propose a new semantic contract for the catalog +title: "[Contract Proposal]: " +labels: ["new-contract", "needs-validation"] +body: + - type: markdown + attributes: + value: | + ## How This Works + + Propose a new semantic contract — a composition of anchors that defines behavior for a specific workflow or context. + + 1. **You provide the contract name and scope** + 2. **Maintainers validate** whether it meets the contract criteria + 3. **If accepted**: The contract is implemented and a PR is submitted + 4. **If rejected**: Maintainers explain why + + - type: input + id: term + attributes: + label: Proposed Contract Name + description: The name of the semantic contract you want to propose + placeholder: "e.g., \"Architecture Documentation\", \"Code Review\", \"Requirements Discovery\"" + validations: + required: true + + - type: textarea + id: anchors + attributes: + label: Constituent Anchors + description: Which existing anchors should this contract compose? + placeholder: | + - arc42 + - c4-diagrams + - madr + validations: + required: true + + - type: textarea + id: context + attributes: + label: Context & Use Case + description: When and why would someone activate this contract? + placeholder: Describe the workflow or scenario this contract supports + validations: + required: true + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission Checklist + options: + - label: The constituent anchors already exist in the catalog + required: true + - label: This contract addresses a recurring workflow (not a one-off) + required: true diff --git a/.github/ISSUE_TEMPLATE/process-proposal.yml b/.github/ISSUE_TEMPLATE/process-proposal.yml new file mode 100644 index 00000000..1edf4c02 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/process-proposal.yml @@ -0,0 +1,53 @@ +name: ⚙️ Process Proposal +description: Propose a change to project processes or governance +title: "[Process Proposal]: " +labels: ["process", "discussion"] +body: + - type: markdown + attributes: + value: | + ## Process Change Proposal + + Suggest a change to how the project operates — contribution workflows, review policies, naming conventions, automation, etc. + + - type: input + id: title + attributes: + label: Proposal Title + description: A concise name for the process change + placeholder: "e.g., \"Make evaluation specs mandatory for new anchors\"" + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem does this process change solve? + placeholder: | + Currently... + This causes... + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed Change + description: What specifically should change? + placeholder: | + I propose that... + validations: + required: true + + - type: textarea + id: impact + attributes: + label: Impact Assessment + description: Who is affected and what's the cost of adoption? + placeholder: | + - Affected parties: ... + - Migration effort: ... + - Risk: ... + validations: + required: false diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index a736b85a..60d0e238 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -271,6 +271,52 @@ For *code changes*: This project uses *CodeRabbit* for automated AI code review on all PRs. CodeRabbit reviews are advisory — human maintainer approval is still required. +== Issue Title Convention + +All issues should follow a consistent `[Type]: ` title format. This makes filtering, searching, and triaging materially easier. + +=== Recognized Prefixes + +[cols="1,2,1"] +|=== +| Prefix | Used For | Source + +| `[Anchor Proposal]:` +| New semantic anchor proposals +| Issue template + +| `[Contract Proposal]:` +| New semantic contract proposals +| Issue template + +| `[Improve]:` +| Improvements to existing anchors +| Issue template + +| `[Bug]:` +| Bug reports +| Issue template + +| `[Process Proposal]:` +| Changes to project processes +| Issue template + +| `[Feature]:` +| Feature requests +| Free-form + +| `EPIC:` +| Tracking issues for larger initiatives +| Free-form +|=== + +=== Guidelines + +- *Use the issue template* whenever one exists — the prefix is set automatically. +- *Free-form issues* (no matching template) should manually use one of the recognized prefixes. +- *Apply going forward only* — do not retro-rename closed issues. +- *EPICs* use the bare `EPIC:` prefix without brackets, as a sanctioned exception. + == Code of Conduct * Be respectful and constructive in discussions diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 05d9e842..85b7d7e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -213,6 +213,29 @@ npm run build 3. Maintainers create the anchor file and PR 4. Community reviews the PR +## Issue Title Convention + +All issues should follow a consistent `[Type]: ` title format. This makes filtering, searching, and triaging materially easier. + +### Recognized Prefixes + +| Prefix | Used For | Source | +|--------|----------|--------| +| `[Anchor Proposal]:` | New semantic anchor proposals | Issue template | +| `[Contract Proposal]:` | New semantic contract proposals | Issue template | +| `[Improve]:` | Improvements to existing anchors | Issue template | +| `[Bug]:` | Bug reports | Issue template | +| `[Process Proposal]:` | Changes to project processes | Issue template | +| `[Feature]:` | Feature requests | Free-form | +| `EPIC:` | Tracking issues for larger initiatives | Free-form | + +### Guidelines + +- **Use the issue template** whenever one exists — the prefix is set automatically. +- **Free-form issues** (no matching template) should manually use one of the recognized prefixes. +- **Apply going forward only** — do not retro-rename closed issues. +- **EPICs** use the bare `EPIC:` prefix without brackets, as a sanctioned exception. + ## Code of Conduct ### Our Pledge diff --git a/docs/CONTRIBUTING.de.adoc b/docs/CONTRIBUTING.de.adoc index 343a03ba..b41f4b83 100644 --- a/docs/CONTRIBUTING.de.adoc +++ b/docs/CONTRIBUTING.de.adoc @@ -184,6 +184,52 @@ Anker sind mit beruflichen Rollen getaggt, um relevante Inhalte zu filtern: . Team Lead / Engineering Manager . Educator / Trainer +== Issue-Titel-Konvention + +Alle Issues sollten einem konsistenten `[Typ]: ` Titelformat folgen. Dies macht Filtern, Suchen und Triagieren wesentlich einfacher. + +=== Anerkannte Prefixe + +[cols="1,2,1"] +|=== +| Prefix | Verwendet für | Quelle + +| `[Anchor Proposal]:` +| Vorschläge für neue semantische Anker +| Issue-Template + +| `[Contract Proposal]:` +| Vorschläge für neue semantische Contracts +| Issue-Template + +| `[Improve]:` +| Verbesserungen an bestehenden Ankern +| Issue-Template + +| `[Bug]:` +| Fehlermeldungen +| Issue-Template + +| `[Process Proposal]:` +| Änderungen an Projektprozessen +| Issue-Template + +| `[Feature]:` +| Feature-Anfragen +| Frei formuliert + +| `EPIC:` +| Tracking-Issues für größere Initiativen +| Frei formuliert +|=== + +=== Richtlinien + +- *Verwenden Sie das Issue-Template*, wann immer eines existiert — das Prefix wird automatisch gesetzt. +- *Frei formulierte Issues* (kein passendes Template) sollten manuell eines der anerkannten Prefixe verwenden. +- *Nur zukünftig anwenden* — geschlossene Issues nicht rückwirkend umbenennen. +- *EPICs* verwenden das bloße `EPIC:` Prefix ohne Klammern als anerkannte Ausnahme. + == Verhaltenskodex * Seien Sie respektvoll und konstruktiv in Diskussionen From 1d0989690df8647bdcfcd0ba57b0d8c990745efb Mon Sep 17 00:00:00 2001 From: jensgrote Date: Tue, 2 Jun 2026 15:23:24 +0200 Subject: [PATCH 2/2] fix: use AsciiDoc list markers (*) instead of Markdown (-) --- CONTRIBUTING.adoc | 8 ++++---- docs/CONTRIBUTING.de.adoc | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 60d0e238..d084e9a9 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -312,10 +312,10 @@ All issues should follow a consistent `[Type]: ` title format. This makes === Guidelines -- *Use the issue template* whenever one exists — the prefix is set automatically. -- *Free-form issues* (no matching template) should manually use one of the recognized prefixes. -- *Apply going forward only* — do not retro-rename closed issues. -- *EPICs* use the bare `EPIC:` prefix without brackets, as a sanctioned exception. +* *Use the issue template* whenever one exists — the prefix is set automatically. +* *Free-form issues* (no matching template) should manually use one of the recognized prefixes. +* *Apply going forward only* — do not retro-rename closed issues. +* *EPICs* use the bare `EPIC:` prefix without brackets, as a sanctioned exception. == Code of Conduct diff --git a/docs/CONTRIBUTING.de.adoc b/docs/CONTRIBUTING.de.adoc index b41f4b83..debc21ac 100644 --- a/docs/CONTRIBUTING.de.adoc +++ b/docs/CONTRIBUTING.de.adoc @@ -225,10 +225,10 @@ Alle Issues sollten einem konsistenten `[Typ]: ` Titelformat folgen. Dies === Richtlinien -- *Verwenden Sie das Issue-Template*, wann immer eines existiert — das Prefix wird automatisch gesetzt. -- *Frei formulierte Issues* (kein passendes Template) sollten manuell eines der anerkannten Prefixe verwenden. -- *Nur zukünftig anwenden* — geschlossene Issues nicht rückwirkend umbenennen. -- *EPICs* verwenden das bloße `EPIC:` Prefix ohne Klammern als anerkannte Ausnahme. +* *Verwenden Sie das Issue-Template*, wann immer eines existiert — das Prefix wird automatisch gesetzt. +* *Frei formulierte Issues* (kein passendes Template) sollten manuell eines der anerkannten Prefixe verwenden. +* *Nur zukünftig anwenden* — geschlossene Issues nicht rückwirkend umbenennen. +* *EPICs* verwenden das bloße `EPIC:` Prefix ohne Klammern als anerkannte Ausnahme. == Verhaltenskodex