bonedigger ā issue templates#
When to Use#
- Editing
templates/or.github/workflows/sync-templates.yml - Checking form fields, issue types, labels, or downstream delivery
- Investigating a failed sync or a branch pushed without a corresponding PR
When NOT to Use#
- Changing the executable reporting client or image packaging ā those belong in common
- Changing issue lifecycle ā Hive owns triage and queues
- Hand-editing synchronized downstream copies instead of their canonical source
Core Process#
- Read the canonical forms and current workflow before changing their contract.
- Preserve the declared consumer roster unless a maintainer approves a change:
projectbluefin/commonprojectbluefin/dakotaprojectbluefin/knuckle
Keepmatrix.repoand the App-tokenrepositoriesscope aligned. Check whether
each destination is archived, writable, and still a consumer; a listed target
is not proof it can receive changes. Do not silently drop archived destinations.
- Use the mergeraptor GitHub App token pattern, not a PAT. The workflow reads
secrets.MERGERAPTOR_APP_IDandsecrets.MERGERAPTOR_PRIVATE_KEY; check secret
availability and App installation permissions without exposing their values. - Follow the existing delivery path:
- A push to
mainchangingtemplates/**triggers synchronization. - Check out bonedigger and each downstream repository.
- Copy all
templates/*.ymlintodownstream/.github/ISSUE_TEMPLATE/. - Commit and push
bonedigger/sync-templates-<sha8>if the remote branch is
absent; otherwise reuse it without rewriting maintainer commits. - Open a PR against
testingfor Dakota andmainfor the other consumers,
without requesting labels that may not exist in the destination. PR creation
failures remain visible and fail the sync step. - Review and merge downstream PRs before calling the forms deployed.
- A push to
- Keep per-repository
cancel-in-progress: false. Cancellation after push but
before PR creation can strand a remote branch. Serialization does not make
reruns idempotent or preserve every pending run. - Pin external actions to full SHAs with version comments. Internal
projectbluefin/actions/*andprojectbluefin/bonedigger/*references may use
version tags, including subpaths. - Validate local changes, then inspect the delivery run and downstream PRs for
the exact revision. A YAML parse, a clean lint, or an absent CI check is not
proof that GitHub renders the forms or consumers received them.
Current form contract#
| File | Issue type | Declared labels | Required inputs |
|---|---|---|---|
bug-report.yml | Bug | none | report-link, what-happened |
feature-request.yml | Feature | none | problem, solution |
help-this-project.yml | none | none | target-url, flow, goal |
config.yml | chooser configuration | none | blank_issues_enabled: true |
Labels are declarations, not label creation. GitHub omits a form's label if it
is absent from the destination repository, and consumers do not share a common
label set, so the forms declare no labels; bug/feature classification is carried
by the issue type. Inspect destination labels and enabled
organization issue types before relying on them for routing. This repository
ships no donation fast-track or approval workflow; the help form's text does not
prove Hive integration exists or that the request was admitted to a queue.
The bug form currently requires a gist URL, but the shipped client
creates an issue directly and uploads a gist only for selected smart-log profiles.
It does not open the form or prefill report-link. Do not tell a user that running
ujust report always produces a gist for this form, or recommend inventing a URL.
Correcting that mismatch requires a canonical template change, not documentation
that pretends the current field is optional.
Delivery hazards to verify#
- New files: change detection relies on
git add -Astaging the copied forms
beforegit diff --cached --quiet; a plaingit diff --quietwould not see
untracked additions. Exercise an added form, a changed form, and an unchanged
copy when changing detection; test both destination bases, not only common's
mainpath. - Chooser configuration: copying
config.ymlreplaces the destination file.
The canonical file has nocontact_links, so existing downstream links can be
lost. Review the config diff before merging a sync PR. - Reruns: a per-SHA branch may already exist after a partial failure. A fresh
rerun reuses that remote branch and retries PR creation without force-pushing.
If the PR already exists, creation still fails visibly; inspect the existing
PR before retrying again. Do not describe the current workflow as fully
idempotent. - Revisions and triggers: re-running a failed run retains its original
commit/ref; it does not test a subsequent repair onmain. A workflow-only
change does not match thetemplates/**push filter, so deliver it with a
workflow_dispatchrun onmain.
Use actual job logs to distinguish startup/token failure from shell-script or
PR-creation failure. Do not diagnose missing secrets merely from an old run's
failure when the source has changed.
Common Rationalizations#
- "The copied files exist, so the sync worked." ā Verify the branch, PR, merge, and form.
- "A label in YAML will be created." ā Labels must already exist downstream.
- "Re-running an old failure tests the latest fix." ā Check the run's original revision.
- "Pre-commit runs every test." ā Only configured hooks run; inspect their coverage.
Red Flags#
- A declared consumer is archived, unavailable, or omitted from the token scope.
- A new template is skipped, a config diff deletes contact links, or a push has no PR.
- Form instructions promise a required gist that the client may not create.
- Donation routing or lifecycle transitions attributed to a workflow this repo lacks.
- Floating external action tags or cancellation of in-progress sync jobs.
Verification#
- Canonical form IDs, required fields, types, and labels match their intended contract.
- Destination label/type availability and archived status have been checked.
- Workflow matrix and App-token scope match the declared consumer roster.
- PR bases are
testingfor Dakota andmainelsewhere. - New, modified, and unchanged files are exercised when sync behavior changes.
- Chooser links and rerun behavior are reviewed before downstream merges.
-
pre-commit run --all-filesandactionlint .github/workflows/*.ymlpass. - Applicable checks and downstream delivery are verified for the actual revision.
Pre-commit currently checks YAML syntax and workflow policy, not GitHub issue-form
schema or unit tests. The pr-validate workflow
(.github/workflows/pr-validate.yml) runs on pull requests to main and
merge-queue groups: it executes python3 -m unittest discover -s tests and then
pre-commit run --all-files. The unit tests include tests/test_issue_forms.py,
which checks the forms against GitHub's issue-form syntax, and
tests/test_consumer_roster.py, which keeps the matrix, token scope, and the
roster above aligned. Neither proves GitHub renders the forms or that consumers
received them. Report the actual coverage rather than inferring it.