docs: realign guides and CONTRIBUTING with the shipped contracts#292
Merged
Conversation
Four drifts surfaced by the 2026-07-20 architecture audit, each verified against the tree: - DeterministicTesting (en+fr): Clock.UseAny()/InstanceIds.UseAny() are parameterless; reproducibility flows through Dummies.Any.Reproducibly(...), not an "optional seed". - CONTRIBUTING.fr: add the missing `binder` and `dummies` commit scopes so the French list matches the English one and commit-lint (7 scopes). - French user guides: fix the dead footer anchor README.fr.md#-etapes-suivantes to #-documentation (FR mirror of 7cf826a). - CONTRIBUTING (en+fr): document that a commit's scope routes it to a release train (tools/trains.sh) and that an unscoped feat:/fix: is silently dropped from the release notes and changelog; refresh the stale future-tense "Adoption" paragraph now that the hook and CI check exist. Refs: #231
This was referenced Jul 23, 2026
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.
Summary
Fix the four documentation/contract drifts surfaced by the 2026-07-20 architecture audit: each is a place where following the docs produced a wrong result. They are realigned with the shipped API, the linter's scope list, the real anchors, and the release tooling's actual semantics. English and French are kept in lockstep for every touched file.
Type of change
Changes
DeterministicTesting.en.md/.fr.md—Clock.UseAny()andInstanceIds.UseAny()are parameterless; corrected the stale "both take an optional seed" claim to point atDummies.Any.Reproducibly(...), which is how reproducibility actually flows since the ADR-0026 rebase.CONTRIBUTING.fr.md— added the missingbinderanddummiescommit scopes so the French scope table matches the English one and the enforcingcommit-lint(7 scopes, not 5).README.fr.md#-étapes-suivantes→#-documentation(the heading was renamed; this is the French mirror of the English fix7cf826a, which was never applied to the FR pages). The two dated audit files that quote the dead anchor as a finding are intentionally left unchanged.CONTRIBUTING.md/CONTRIBUTING.fr.md— rewrote the commit-scope paragraph: the scope now routes a commit to a release train (tools/trains.sh:lib/cli/dum), so an unscopedfeat:/fix:matches no train and is silently dropped from that train's release notes and changelog. Documented the mapping, linkedAddingAReleaseTrain, and warned about the unscoped-commit consequence. Also refreshed the stale future-tense "Adoption" paragraph now that thecommit-msghook and CI check already exist.Testing
Documentation-only change (Markdown; no code, analyzers, or tooling touched), so no build or test suite was run:
dotnet build FirstClassErrors.sln— not run (no code change)dotnet test FirstClassErrors.sln— not run (no code change)FirstClassErrors.Analyzers.UnitTests) — not run (no analyzer change)Verified instead against the tree: no
optional seed/graine optionnelleremains; the FR scope table now has 7 rows matching the linter list; 0 dead#-étapes-suivantesanchors remain in the user guides (25 now point at#-documentation); and theAddingAReleaseTrainlinks resolve from both file locations.Documentation
doc/updatedDeterministicTesting,CONTRIBUTING, and the 20 user guides).README.fr.mditself is not among the touched files.Architecture decisions
Proposed: ADR-____The changes only realign documentation with decisions and tooling already in place (ADR-0026 for
UseAnyreproducibility; the release-train partition intools/trains.sh). Advisory follow-up, not in this PR: makingcommit-lintrequire a scope onfeat:/fix:— the mechanical closure of the footgun this PR documents — would be a behaviour change worth its own ADR.Related issues
Closes #231
🤖 Generated with Claude Code
Generated by Claude Code