docs/CALVER.md links to .changeset/README.md, which does not exist
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 2.1k
- Forks
- 443
- Avg merge
- 4d 19h
- Merged PRs (30d)
- 24
Description
Which package or tool is having this issue?
Other (documentation)
What version of that package or tool are you using?
main @ b543c6d2
Steps to Reproduce
Open the "Related Documentation" section at the end of docs/CALVER.md and follow the last bullet:
- [.changeset/README.md](../.changeset/README.md) - Changesets documentation
Expected Behavior
The link resolves to a file in the repository.
Actual Behavior
.changeset/README.md does not exist. The .changeset/ directory contains only config.json and the CalVer scripts:
calver-bump-type.test.js enforce-calver-ci.js
calver-shared.js enforce-calver-local.js
changeset-protection-utils.js get-calver-version-branch.js
check-major-protection.js hydrogen-changelog-config.js
config.json process-major-version-bypass.js
detect-calver-bump-type.js test-calver-comparison.sh
There are two reasonable fixes and the choice is yours to make:
- Remove the bullet, if the changesets documentation in
CONTRIBUTING.mdis considered sufficient. - Add
.changeset/README.md, if the CalVer scripts in that directory warrant their own documentation.
I did not include a fix in the accompanying PR because either option is a decision about intent rather than a correction.
Suggestion: a link check in CI
This link, and the two corrected in the PR below, all rot the same way. Files move, headings get renamed, and nothing verifies the markdown that points at them. format:check covers formatting only, and its scope is ./packages ./templates, so docs/ is not checked at all today.
A CI step that resolves relative markdown links would catch this class of problem at the point it is introduced. Scope worth deciding up front:
- Relative links only, or external URLs as well. External URL checking is slower and prone to false positives from rate limiting.
- Whether to check heading anchors, not just file paths.
- Which paths to cover.
cookbook/llms/*.prompt.mddeliberately uses paths relative to a scaffolded app rather than this repo, so it would need excluding.
I am happy to implement this if it is wanted. It is intentionally not part of the linked PR, so that the two straightforward corrections there can be reviewed on their own.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in the Related Documentation section of docs/CALVER.md and compare the broken .changeset/README.md reference with the changeset guidance in CONTRIBUTING.md. Decide whether the missing README should be removed or added based on the CalVer scripts' documentation needs, then verify that the link resolves and the surrounding documentation remains accurate.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100