From da43f967967dde82ea33b0eaa7b1f6c664053690 Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl Date: Tue, 1 Sep 2026 15:34:46 +0000 Subject: [PATCH] docs: add repository intake forms --- .github/ISSUE_TEMPLATE/config.yml | 12 +++++ .github/ISSUE_TEMPLATE/proposal.yml | 34 ++++++++++++ .github/ISSUE_TEMPLATE/work-order.yml | 75 +++++++++++++++++++++++++++ CONTRIBUTING.md | 5 +- changelog.d/50.md | 1 + 5 files changed, 125 insertions(+), 2 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/proposal.yml create mode 100644 .github/ISSUE_TEMPLATE/work-order.yml create mode 100644 changelog.d/50.md diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..546bb99 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,12 @@ +# The new-issue interception (issue #24, decision 1): interception over +# instruction — prose alone has already proven insufficient everywhere else +# in this org. Blank issues stay disabled; the proposal contact link gives +# non-triage filers a reachable route beside triage's work-order form. That +# chooser is native forge behavior, no automation needed. +blank_issues_enabled: false +contact_links: + - name: Ideas, bugs, questions — file a Proposal + url: https://forgejo.heavyduty.builders/heavy-duty/stoke/issues/new?template=proposal.yml + about: >- + Anyone may file a proposal. Triage converts it into a work issue or + refuses it with reasons; only triage mints work issues (TRIAGE.md). diff --git a/.github/ISSUE_TEMPLATE/proposal.yml b/.github/ISSUE_TEMPLATE/proposal.yml new file mode 100644 index 0000000..4dc3472 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/proposal.yml @@ -0,0 +1,34 @@ +# This intake form applies no labels: queue labels are triage's explicit act +# (LABELS.md), and the issue-flow sweep catches non-triage authors, so the form +# must not pre-judge the proposal's queue state (#24 D2). +name: Proposal (anyone) +description: >- + Share an idea, bug, question, or rough "we should…" for triage to convert + into work or refuse with reasons. +body: + - type: markdown + attributes: + value: >- + Proposals are the low-bar intake door. Say what you noticed and why it + might matter; triage will decide whether it becomes a work issue. + - type: textarea + id: noticed + attributes: + label: What did you notice? + description: A rough idea, bug, question, or "we should…" is enough. + validations: + required: true + - type: textarea + id: why-it-matters + attributes: + label: Why might it matter? + description: Optional — describe the impact or opportunity if you can. + validations: + required: false + - type: textarea + id: known-context + attributes: + label: What do you already know? + description: Optional — add links, examples, constraints, or prior art. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/work-order.yml b/.github/ISSUE_TEMPLATE/work-order.yml new file mode 100644 index 0000000..e8dcd98 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/work-order.yml @@ -0,0 +1,75 @@ +# The issue contract (TRIAGE.md "The issue contract") as a form, so every +# minted issue lands with the same bones and a later parser (#18) can key on +# stable section headings. Consistency, not a gate: the form applies no +# labels — queue labels are triage's explicit act (LABELS.md), and #18's +# sweep is what catches non-triage authors, so the form must not pre-judge +# that (issue #24, decision 2). +name: Work order (triage only) +description: >- + The issue contract (TRIAGE.md) as a form. Only triage mints work issues — + everyone else files a proposal. Triage may still compose by hand when + the form fights it: `stoke issue create --body-file` bypasses forms and stays + legitimate for the triage identity. +body: + - type: markdown + attributes: + value: >- + **The title names the deliverable** — "lib/version.sh — one version + abstraction, two backends", never "improve version handling". The + bar for everything below, stated once: a competent builder who has + read only this issue and the repo can succeed (TRIAGE.md). Labels + (type, `scope:*`, `ready`/`blocked`) are your explicit act after + minting — this form applies none. + - type: textarea + id: context + attributes: + label: Context + description: >- + Why this exists, with links — the proposal it came from, the code + it touches (permalinks at a pinned SHA, so line references cannot + rot), prior art in sibling repos. + validations: + required: true + - type: textarea + id: spec + attributes: + label: Spec + description: >- + Decisions made, not options listed. If the spec still has an open + question, the issue is not ready to exist. + validations: + required: true + - type: textarea + id: tasks + attributes: + label: Tasks + description: The steps, checkboxed, in order. + placeholder: "- [ ] the first step" + validations: + required: true + - type: textarea + id: acceptance-criteria + attributes: + label: Acceptance criteria + description: >- + Checkboxed, verifiable, and honest — these become the builder's + definition of done and the reviewer's review spec, verbatim. + placeholder: "- [ ] a verifiable outcome" + validations: + required: true + - type: textarea + id: test-plan + attributes: + label: Test plan + description: What proves it, including the cases that must fail. + validations: + required: true + - type: textarea + id: dependencies + attributes: + label: Dependencies + description: >- + `Blocked by #N` / `Blocks #N`, and `Part of #E` when an epic + organizes it — or state "None". + validations: + required: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc3541a..b1c44c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,5 +51,6 @@ the ruling's alternatives. ## Work issue ownership -Only triage mints work issues; anyone may file a proposal, which triage converts -or refuses. +Only triage mints work issues; anyone may file a +[proposal](https://forgejo.heavyduty.builders/heavy-duty/stoke/issues/new?template=proposal.yml), +which triage converts or refuses. diff --git a/changelog.d/50.md b/changelog.d/50.md new file mode 100644 index 0000000..4aac40d --- /dev/null +++ b/changelog.d/50.md @@ -0,0 +1 @@ +- Added guided proposal and triage work-order forms, with the contributor guide linking directly to proposal intake. (#50).