From e75fd6e0a54f1d75f2976368919a485f4e98bb2a Mon Sep 17 00:00:00 2001 From: "melodic-standards-sync[bot]" <300666570+melodic-standards-sync[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 20:16:36 +0000 Subject: [PATCH] chore: sync standards components (817897d347764826f2d36c73b31cfc6e024e7ef7) --- .github/workflows/pr-check-managed-files-hosted.yml | 7 +++++++ docs/standards/issue-tracker.md | 6 +++--- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pr-check-managed-files-hosted.yml b/.github/workflows/pr-check-managed-files-hosted.yml index 38cd1e0..d8d7150 100644 --- a/.github/workflows/pr-check-managed-files-hosted.yml +++ b/.github/workflows/pr-check-managed-files-hosted.yml @@ -41,10 +41,15 @@ on: - .editorconfig - .editorconfig-checker.json - .gitattributes + - .github/ISSUE_TEMPLATE/agent-ready.yml + - .github/ISSUE_TEMPLATE/bug-report.yml + - .github/ISSUE_TEMPLATE/feature-request.yml + - .github/ISSUE_TEMPLATE/task.yml - .github/actionlint.yaml - .github/standards/dependabot-policy/policy.json - .github/standards/github-actions-conventions/vocabulary.json - .github/standards/github-actions-conventions/vocabulary.schema.json + - .github/standards/issue-body-contract/contract.json - .github/standards/pyright/pyrightconfig.json - .github/standards/runner-policy/package-lock.json - .github/standards/runner-policy/package.json @@ -83,7 +88,9 @@ on: - eng/dotnet-analysis/Directory.Build.props - eng/dotnet-analysis/dotnet.globalconfig - lychee.toml + - plugins/bugs/reference/issue-body-contract.json - plugins/guardrails/lib/path-detection/machine-path-patterns.sh + - plugins/work-items/reference/issue-body-contract.json permissions: contents: read diff --git a/docs/standards/issue-tracker.md b/docs/standards/issue-tracker.md index ae57fed..027fb4c 100644 --- a/docs/standards/issue-tracker.md +++ b/docs/standards/issue-tracker.md @@ -29,7 +29,7 @@ The naming grammar above governs labels only. Issue titles are free text: there **Structured metadata, not title prefixes.** Set the type with `--type` or the issue form's Types field; set area and other axes with labels. PR titles are unchanged, remaining Conventional Commits enforced by the `pr-contract` composite inside the required `ci-status` check, because squash-merge makes the PR title the default-branch subject line. Issue titles and PR titles serve different layers and follow different rules. -**Issue forms set no title prefix.** GitHub's issue-form examples ship a `title: "[Bug]: "` default; forms here leave `title` empty and set the type through the form's `type:` key instead, so every issue reads the same. +**Issue forms set no title prefix.** GitHub's issue-form examples ship a `title: "[Bug]: "` default; forms here leave `title` empty and set the type through the form's `type:` key instead, so every issue reads the same. The one exception is the agent-ready work-item form, which sets no type: its work can be a bug, a feature or a task, so triage sets the type (the [issue-body contract](https://github.com/melodic-software/standards/blob/main/components/issue-body-contract/README.md#rules-the-contract-keeps) records why). **Open issues conform; closed ones stay.** Retitle an open issue that breaks this rule, unless automation finds that issue by its exact title. Closed issues are not backfilled. @@ -43,13 +43,13 @@ Every issue meets one rule, whether a person, an agent session or a bot workflow - a parent issue when the work belongs to a larger one; - a blocked-by edge when it waits on other work or a decision (see "The status axis" below). -The title and Issue Type are set at filing, always. The filer sets the other values it knows at filing; triage sets the rest before the issue is worked, and no value is ever a placeholder. A bot that files the same kind of record repeatedly (a post-merge alert, a monitoring incident) knows these values and sets them at filing. An issue tracks work with an owner, so a bot's current status belongs in its run's job summary; it files an issue only for an incident that needs action, one per incident. +The title and Issue Type are set at filing, always, except on an issue filed through the agent-ready work-item form, whose type triage sets. The filer sets the other values it knows at filing; triage sets the rest before the issue is worked, and no value is ever a placeholder. A bot that files the same kind of record repeatedly (a post-merge alert, a monitoring incident) knows these values and sets them at filing. An issue tracks work with an owner, so a bot's current status belongs in its run's job summary; it files an issue only for an incident that needs action, one per incident. ## The type axis On organization repositories the type axis is **native GitHub Issue Types**, not labels. Issue Types are an organization-level, single-select field: an issue carries **at most one** type, never two. GitHub positions them as the successor to a type-prefixed label. They are the governance mechanism for this axis; there is no parallel type label alongside them. GitHub does not require every issue to carry a type: search exposes a positive `type:"Bug"`-style qualifier per enabled type but no `no:type` negation to find the untyped remainder directly (querying `no:type` silently returns the unfiltered total, not a filtered one), so finding what's missing means comparing per-type counts against the total or reading an issue's `type` field, which is `null` when unset. An issue created via a form or API call that skips the field can silently fall outside the taxonomy this way. -**Issue creation always sets the type.** CLI and agent-driven issue creation passes `--type` with one of the org's enabled native types, for example `gh issue create --type Task` (or `Bug`/`Feature`, whichever applies). The web UI's issue form surfaces the same Types field at creation time, but GitHub does not force it to be filled in there either; setting it is this policy's requirement, not something the platform enforces on either path. github-iac does not assign a type on a schedule; [ADR 0003](https://github.com/melodic-software/github-iac/blob/main/docs/adr/0003-issue-type-axis-native-issue-types.md) deleted that sweep. An issue that skips the field stays untyped until a person or the triage lane sets one of the live organization types. +**Issue creation always sets the type**, apart from the agent-ready work-item form above. CLI and agent-driven issue creation passes `--type` with one of the org's enabled native types, for example `gh issue create --type Task` (or `Bug`/`Feature`, whichever applies). The web UI's issue form surfaces the same Types field at creation time, but GitHub does not force it to be filled in there either; setting it is this policy's requirement, not something the platform enforces on either path. github-iac does not assign a type on a schedule; [ADR 0003](https://github.com/melodic-software/github-iac/blob/main/docs/adr/0003-issue-type-axis-native-issue-types.md) deleted that sweep. An issue that skips the field stays untyped until a person or the triage lane sets one of the live organization types. Personal accounts have no native Issue Types, so their repositories retain a labeled type axis under the same naming grammar. This is a deliberate per-account divergence, not drift; each account's own infrastructure-as-code program is the record of which mechanism its repositories use (see "Definitions live in infrastructure-as-code" above).