Enables the Docs and doc links gate stages - #231
Merged
Merged
Conversation
mix quality now checks the package's docs before a publish would. The Docs stage runs mix docs and fails on any ExDoc warning; the Doc links stage fails on the link rules ExDoc accepts silently: a README relative link to a file not in the package files, a published relative link to a file that is not an extra, two extras sharing a basename, a silent rewrite to a different extra. Both are opt-in in ex_quality and are set to enabled: :auto in .quality.exs, with that reason beside them. The doc links stage ships in ex_quality 0.15.0, so the dev dependency requirement moves from ~> 0.14 to ~> 0.15 with its other options unchanged, and mix deps.update ex_quality moves only ex_quality in mix.lock (0.14.0 to 0.15.0). This is a dependency requirement change; the package's own version does not move. Both stages run and pass on main's docs, so the gate starts green. The loop profile's stage list is unchanged and does not run them. No changelog fragment: changelog.d/README.md excludes quality gate changes. Refs: px-9ejw
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
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.
Refs px-9ejw.
What
mix qualitynow checks this package's docs before a publish would:.quality.exsenables the two opt-in docs stages,docs: [enabled: :auto]anddoc_links: [enabled: :auto], with the reason beside them.mix.exsmoves the dev dependency requirement on ex_quality from~> 0.14to~> 0.15(the release that ships the Doc links stage), its other options unchanged.mix.lockmoves ex_quality only, 0.14.0 to 0.15.0, viamix deps.update ex_quality.This package's own version does not move. No changelog fragment:
changelog.d/README.mdexcludes quality gate changes.The reason comment, as it stands in
.quality.exs:The header comment's list of full-gate stages gains "docs, doc links". The
loopprofile names its stages explicitly ([:format, :compile, :credo, :test]), so the inner loop does not run either new stage.Why this gate change is in order
This repository's gate record,
docs/adr/0008-the-quality-gate-and-its-non-editable-config.md("Deliberately retuning the gate is ordinary work, not a violation"), makes enabling a check ordinary work when it is the bead's purpose: proposed as the work, reviewed on its own, carryingarea:build, landing onmainalone. This PR is exactly that and nothing else. The operator's standing campaign consent authorizes this gate change (its gate-change clause).Evidence
ex_quality 0.15.0 is on Hex (
mix hex.info ex_quality, excerpt):git diff origin/main --stat:The
mix.lockdiff (one line out, one line in; no other dependency moves):Full
mix qualityon the committed tree (a fresh worktree, so the dependency compile precedes the gate), quoted whole. Docs and Doc links both ran and passed:The commit was made on the tree this run went green on (same
git write-tree), so the commit step did not re-run the gate.Review (in-turn)
Tier: gate. Config only: three files, no
lib/ortest/change, no public surface, 24 lines changed. I re-read the diff against the bead and its acceptance criteria: the requirement reads{:ex_quality, "~> 0.15", only: :dev, runtime: false}with the other options as they were; the lock diff moves ex_quality alone; both stages areenabled: :auto; the gate reports both as run and passing, not skipped. I checked the reason comment against ex_quality 0.15.0's own docs: its stage table says Docs runsmix docs, failing on any ExDoc warning, and that both stages are opt-in; its Doc links moduledoc documents:autoas "on when:ex_docis installed" for both, and the four link rules in the comment are the ones the bead names. Doc links found nothing on main's docs, so no doc edit was needed and the diff stays withinmix.exs,mix.lockand.quality.exs.test/docs_adr_links_test.exsis untouched and still passes in the suite.