Shopify / Shopify/hydrogen

docs/CALVER.md links to .changeset/README.md, which does not exist

Open Beginner friendly
#4,013 0 comments 0 reactions 0 assignees View on GitHub

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:

  1. Remove the bullet, if the changesets documentation in CONTRIBUTING.md is considered sufficient.
  2. 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.md deliberately 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.