Skip to content

Put bug reports and feature requests on the house forms - #86

Open
rahlk wants to merge 1 commit into
mainfrom
docs/house-style-bug-and-feature-forms
Open

rahlk wants to merge 1 commit into
mainfrom
docs/house-style-bug-and-feature-forms

Conversation

@rahlk

@rahlk rahlk commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Converts bug_report.md and feature_request.md into issue forms that match the discipline epic.yml and work_item.yml already ask for.

Motivation and Context

ISSUE_TEMPLATE/ held two shapes. epic.yml and work_item.yml require a scope boundary, caveats and a definition of done. bug_report.md and feature_request.md were stock GitHub boilerplate — "A clear and concise description of what the bug is" — and being markdown templates, none of their fields were required.

The weaker pair set the example for every repo in the org that inherits these templates, which is all of them.

How Has This Been Tested?

Both forms parse:

$ python3 -c "import yaml; yaml.safe_load(open('.github/ISSUE_TEMPLATE/bug_report.yml')); print('valid')"
valid
$ python3 -c "import yaml; yaml.safe_load(open('.github/ISSUE_TEMPLATE/feature_request.yml')); print('valid')"
valid

Not yet rendered in GitHub's form UI — that only happens once this is on main. Worth a look at the chooser afterwards.

Checked that nothing references the old filenames: CONTRIBUTING.md names the templates by role, not by path.

Breaking Changes

bug_report.md and feature_request.md are deleted, so any link to those paths breaks. Nothing in this repo linked them. Links elsewhere in the org are unverified — I did not sweep the other repos.

Existing issues are unaffected; templates apply at creation.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the Codellm-Devkit Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally — this repo has no test suite; YAML validation above stands in
  • I have added appropriate error handling — n/a, no executable code
  • I have added or updated documentation as needed

Additional context

The forms keep the house discipline without borrowing maintainer-only sections a reporter cannot fill:

  • bug_report — reproduction and observed-vs-expected must be pasted, not paraphrased. The scope-boundary slot becomes What you have not checked: a reporter knows their own unknowns, not the fix's boundary. Marking a guess as a guess is required, because an unmarked one sends the next person to fix something that is not broken.
  • feature_request — scope boundary, alternatives considered, caveats, and an observable "what done would look like". States up front that schema and public-API changes get designed before they get built, so proposals stop arriving with a field layout already chosen.

CONTRIBUTING.md's "Writing a good issue" said "both templates"; it now covers all four issue forms plus the PR template, and says plainly that gh issue create --body bypasses the form.

Blank issues are still enabled — this PR does not change config.yml.

The matching skill-side change is codellm-devkit/cldk-devtools#docs/issue-prose-budget, which stops the skills keeping a second copy of these forms.

bug_report.md and feature_request.md were stock GitHub boilerplate -- "a clear and
concise description of what the bug is" -- while epic.yml and work_item.yml ask for
a scope boundary, caveats and a definition of done. Two shapes in one ISSUE_TEMPLATE
directory, and the two markdown ones set the weaker example.

Both become issue forms, so the required fields are enforced at submit time rather
than by review. They keep the house discipline without borrowing maintainer-only
sections that a reporter cannot fill:

- bug_report: reproduction and observed-vs-expected are pasted, not paraphrased.
  The scope-boundary slot becomes "What you have not checked" -- a reporter knows
  their unknowns, not the fix's boundary.
- feature_request: scope boundary, alternatives considered, caveats, and an
  observable "what done would look like". Says up front that schema and public-API
  changes get designed before they get built, so proposals stop arriving with a
  field layout already chosen.

CONTRIBUTING's "Writing a good issue" said "both templates" and now covers all
four plus the PR template, with the rule that `gh issue create --body` bypasses
the form silently.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant