docs: KEEP-1132 add contribution guide and require an accepted issue - #98
Merged
Merged
Conversation
This repo had no CONTRIBUTING.md. Adds one covering the real build (make build/test/lint, the sync-version step, `go generate ./docs/` which CI fails on drift) and ISSUES.md as the contribution policy. Anything that changes command behaviour needs an issue marked `accepted` before the pull request, referenced in the PR title after the conventional-commit type (`feat: #97 description`). The type prefix still drives release-please. Issue forms and pr-issue-link.yml match the keeperhub setup, retargeted to main since this repo has no staging branch. Needs before this is useful: the `accepted`, `needs-triage` and `no-issue-required` labels.
Mirrors the keeperhub change. Issue forms restructured around three required parts: reason (command, output, expectation and its source, what it costs), scope (commands affected, siblings checked, one problem), and plan (the filer's proposal, which triage may replace in a comment before accepting). Adds `confirmed` so reproducing an issue is separable from deciding to fix it.
Mirrors the keeperhub change: nothing applies retroactively, a filer is never asked to restate what they already said, and compound issues are split by us with the reporter credited on each part.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion to KeeperHub/keeperhub#2003, which carries the full rationale. This repo had no
CONTRIBUTING.mdat all, so that is written from scratch here alongside the policy.What is here
CONTRIBUTING.md- new. The real build:make build/test/lint, thesync-versionstep that copies.release-please-manifest.jsonintointernal/version/(build with plaingo buildand the binary reports the wrong version), andgo generate ./docs/, which thedocs-checkjob fails on drift.ISSUES.md- the policy. Anything that changes command behaviour, output, or exit codes needs an issue markedacceptedfirst. Typos, help-text wording, and docs matching existing behaviour go straight to a pull request..github/ISSUE_TEMPLATE/- bug and behaviour-change forms; free-text issues off..github/PULL_REQUEST_TEMPLATE.md.github/workflows/pr-issue-link.yml- the gate, retargeted tomainsince this repo has nostagingbranch.Every issue carries a reason (command, output, the expectation and what told you to expect it, what it costs), a scope (commands affected, siblings checked, one problem), and a plan (the filer's proposal, which triage may replace in a comment before accepting).
Title format
<type>: #<issue> <description>, for examplefeat: #97 add --require-verified to execute status. The type prefix still drives release-please, so it stays accurate.This repo has no
pr-title-check, and this PR does not add one - that is a separate change if you want it.Worked example already in the queue
PR #95 bundles receipt rendering plus
--require-verifiedwith an unrelated--timeoutdeadline for--watch. Neither needs the other to be correct, and the timeout changes behaviour for every existing--watchcaller. Under this policy that is two issues and two pull requests, settled before either was written. It is used as the split-test example inISSUES.md.Before this is useful
The same labels as the keeperhub PR (
accepted,confirmed,needs-triage,needs-discussion,no-issue-required) have to exist on this repo, or every non-exempt PR fails the gate.Nothing applies retroactively: PR #95 and any existing issues are grandfathered, and no filer is asked to resubmit through a form that did not exist when they filed.