docs(governance): add CONTRIBUTING.md and the two issue forms - #501
Merged
Conversation
GitHub surfaces governance files by filename, and this repository had none, so none of the guides it does have were reachable from the places a contributor actually looks: the sidebar link, the banner on a new issue, the "how do I report this" moment. The content already existed — `.github/contributing/*` are thorough, `AGENTS.md` is a strong de-facto guide — it was simply invisible (#97). `CONTRIBUTING.md` is a map, not a guide. A table routing each intent to the file that already answers it, plus the few things a first pull request needs to know and nothing else: the pinned Node and pnpm, that `dev:prepare` comes before anything typechecks, that the title is a conventional commit and is load-bearing because the squashed subject generates the changelog, and that snapshots are regenerated with the whole suite. Two issue forms. The bug report requires a reproduction and says why in the field itself: most reports that look like a defect here depend on something in the application around the component, and prose cannot separate those. It also asks whether the behaviour reproduces upstream, because this is a fork and a bug present in Nuxt UI is fixed differently from one introduced by a port. The feature request asks for the problem before the proposal, and asks whether the thing already exists upstream — "port and reconcile" is a different and much shorter conversation than "design and build". Blank issues stay enabled: the maintainer files audit notes and follow-ups that fit neither form. The README's contribution section promised a "reporting bugs guide" and linked nothing at all. It now links the form, the guide, and CONTRIBUTING.md. `documented-scripts.spec.ts` gains `CONTRIBUTING.md`, so a command quoted there that does not exist fails a test rather than costing every reader a minute. Verified by mutation. `README.md` stays out of that list on purpose: its `pnpm` lines install this package into somebody else's application. SECURITY.md and CODE_OF_CONDUCT.md are deliberately not here. Both need a private contact to report into, the repository publishes none, and inventing one would send a reporter into a void — deferred to the maintainer's decision along with the CODEOWNERS entry and branch protection.
Two reviewers flagged the same sentence independently. Under a heading about security, "raise anything urgent with the maintainer through the repository" means a public issue, because that is the only channel this repository has — so the file was instructing vulnerability reporters to disclose to everyone before there is a fix. That is worse than saying nothing. It now says plainly not to open a public issue, and that there is nowhere good to send one yet. The same section claimed a code of conduct and a security policy were "being written". There is no draft, no branch and no issue for either; the claim was a promise that would quietly never land. It now says what is true. Also from review, each checked against the repository first: - The reproduction field was a single-line `input` whose own description asks for a paragraph explaining what blocked a reproduction. Now a `textarea`. - Neither form warned that issues are public. Both now ask for tokens, keys, portal URLs and customer data to be redacted, and the `nuxi info` hint says to read the output first — it prints local paths and the full module list. - "CI runs the same commands" was wrong: CI runs `test:coverage` rather than the plain run, plus `test:module` and `build`, either of which can fail on a branch where the three local commands are green. - `bug-report.yml` set no label while the other form did; `bug` exists. - The title example said `fix(Button)` and the component field said `B24Button`, with nothing saying why they differ. Now stated. - The docs-site contribution page still filtered issues by `label:v3`, which is upstream's label and matches nothing in a fork at 2.x, and still said "open a new issue" with no mention of the forms. `governance-files.spec.ts` covers the two things nothing else could see. An issue form that breaks the schema is not an error anywhere — GitHub stops offering it and falls back to a blank issue box, which looks exactly like a repository that never had forms. And the pinned Node and pnpm versions are quoted as prose in `CONTRIBUTING.md`, where `documented-scripts.spec.ts` only checks script names, so a `packageManager` bump would leave the doc wrong with nothing red. Six mutations, six failures: a `validations` key on a markdown block, an unknown `render` language, a duplicate id, unparseable YAML, a `?template=` link that no longer names a form, and a bumped pnpm version. A parse failure is carried as data rather than thrown, because throwing at collection time reports as "no tests" — the same output as a spec nobody wrote. Found by mutating for it. `yaml` becomes an explicit devDependency; it was only in the tree transitively, through vite.
6 tasks
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
2 participants
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.
Linked issue
Part of #97
Type of change
revert(Scope): ...)Description
The issue's diagnosis was exactly right: the content already exists and GitHub never surfaces it.
.github/contributing/*are thorough,AGENTS.mdis a strong de-facto guide — but none of it is reachable from the places a contributor actually looks, because GitHub finds governance files by filename and there were none.CONTRIBUTING.mdA map, not a guide. A table routing each intent to the file that already answers it, plus the few things a first pull request needs and nothing more:
^20.19.0 || >=22.12.0, pnpm11.20.0, both taken frompackage.jsonrather than recalled.dev:preparecomes first — nothing typechecks before it.vitest run -uafter theme edits #74.Every local path in it is verified to exist, and every
pnpm runcommand in it resolves to a real script — see the guard note below.The two forms
Bug report requires a reproduction and says why in the field itself, rather than treating it as a formality:
It also asks whether the behaviour reproduces in Nuxt UI. This is a fork, and a bug present upstream is fixed differently from one introduced by a port — that answer changes which of the two conversations the report starts.
Feature request asks for the problem before the proposal, on the grounds that a request phrased as a solution can only be accepted or rejected, while one phrased as a problem can be answered with something better. It also asks whether the thing exists upstream: "port and reconcile" is a much shorter path than "design and build".
Blank issues stay enabled — the maintainer files audit notes and follow-ups that fit neither form, and forcing them through a bug template would be a tax on the person filing most of the issues.
README
Line 107 promised a "reporting bugs guide" and linked nothing at all — the exact wording the issue flagged. It now links the form, the section, and
CONTRIBUTING.md.One guard extended
documented-scripts.spec.tschecks that everypnpm run <script>quoted in the contributor docs resolves to a real script.CONTRIBUTING.mdis now in that list, so a typo there fails a test instead of costing every reader a minute. Verified by mutation:dev:prepaerturns it red, naming the file and the script.README.mdstays out on purpose, for the reason already written into that spec — itspnpmlines install this package into somebody else's application, which thispackage.jsonsays nothing about.What is deliberately not here
SECURITY.mdandCODE_OF_CONDUCT.md. Both need a private contact to report into. The repository publishes none — noauthor, nobugs, no email anywhere in tracked files — and thebitrix24organisation has no org-levelSECURITY.mdto inherit. Contributor Covenant has a mandatory contact field, and a security policy pointing at a channel nobody watches is worse than no policy: a researcher either goes silent or goes public. Deferred to the maintainer's decision.CODEOWNERS— the maintainer's call, and without branch protection it changes nothing either way.A second maintainer and branch protection remain the owner actions #97 and its comment already describe. They are the strategically important half and no pull request can deliver them.
One thing worth recording:
CONTRIBUTING.mdoriginally linked to GitHub Discussions. The repository hashas_discussions: false, so that would have shipped a dead link on the first page a contributor reads. Caught by checking rather than by assuming.Checklist
Gate on Node 24:
lint0 ·typecheck0 ·test:coverage316/316 (7444) with thresholds met ·test:module3/3 ·test:workflows49/0.Generated by Claude Code