docs: make catalog versioning easier to understand#117
Merged
Conversation
The rename example used dotted error codes (PAYMENT.DECLINED) while the baseline JSON example in the same guide, and the FCE004 UPPER_SNAKE_CASE convention the library enforces, use underscores. Align the example on that convention in both the English and French guides.
15 tasks
Make the three catalog versioning pages navigable as one unit. The footer links now form a single linear path (operational integration -> guide -> reference -> CI/CD -> architecture) instead of the guide skipping its own sub-pages and the reference and CI/CD footers pointing at each other; every page also gains the "up to the table of contents" link. The README table of contents (English and French) groups the guide, reference, and CI/CD pages under a "Catalog versioning" sub-section, so the three are discoverable and the "table of contents" links land where the pages are actually listed.
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
Restructure the catalog versioning documentation from one long page into a short guide plus dedicated reference and CI/CD pages (English and French), so a reader meets the mental model and the everyday workflow first and reaches implementation detail only when needed. The entry-point filenames are unchanged, so existing links stay valid.
Type of change
Changes
CatalogVersioning.{en,fr}.mdaround the mental model and the daily workflow: snapshot vs committed baseline, whatcatalog updateactually means, a concreteerrors-baseline.jsonexample, and the rename scenario.CatalogVersioningReference.{en,fr}.md: commands, options, exit codes,--fail-on/--report/--against, snapshot & baseline format, schema behavior, andfce.jsonconfiguration.CatalogVersioningCI.{en,fr}.md: GitHub Actions and GitLab CI examples, baseline seeding, label-based acceptance, and release-diff scenarios.UPPER_SNAKE_CASE(PAYMENT_DECLINED), matching theerrors-baseline.jsonexample shown on the same page.Testing
dotnet build FirstClassErrors.slndotnet test FirstClassErrors.slnFirstClassErrors.Analyzers.UnitTests)Documentation-only change; no source code was modified, so the build and test commands do not apply. Verified instead that every cross-page and table-of-contents link resolves, that the footer navigation spine is acyclic in both languages, and that all commits pass the repository commit-lint (
--ci).Documentation
doc/updateddoc/README.fr.md) updated if user-facing behavior changedEvery page exists in English and French and was updated together; the French README table of contents was updated alongside the English one. No user-facing behavior changed.
Related issues
None.