From 8facf1a3a9bc5af909533b5a4cf5de1ef565bebe Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Jul 2026 16:23:23 +0000 Subject: [PATCH 1/2] docs: reorganize documentation into generated and handwritten Split doc/ by content origin so the FirstClassErrors.Documentation project surfaces the whole documentation set instead of only the user-facing part: doc/generated/ CI/CD living documentation (GenDoc target) doc/handwritten/for-users/ former doc/* (guides, analyzers, images) doc/handwritten/for-maintainers/ former maintainers/* (ADRs, workflows) The Documentation project's glob is rooted in doc/, so the sibling maintainers/ tree was invisible in the Solution Explorer; moving it under doc/handwritten lets the single project cover everything. The project and the root README.md stay in place; the README is linked under handwritten/for-users next to its French translation. Every reference to the old paths is updated: root docs (README, CONTRIBUTING, SECURITY, CLAUDE, AGENTS), the PR template and prompts, CI workflow notes, the analyzer IDE help-link base URL (HelpLinks.cs), the shipped RequestBinder NuGet readme, the adr-check context script (a functional path), and every relative link inside the moved Markdown. Structural move only; no content rewritten. Refs: #164 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01YCDL8WVukKYb2mVUnsyPKZ --- .github/adr-check-prompt.md | 4 +- .github/pull_request_template.md | 6 +- .github/workflows/adr-check.yml | 2 +- .github/workflows/canary.yml | 2 +- .github/workflows/ci.yml | 2 +- AGENTS.md | 4 +- CLAUDE.md | 10 ++-- CONTRIBUTING.md | 4 +- FirstClassErrors.Analyzers/HelpLinks.cs | 4 +- .../FirstClassErrors.Cli.csproj | 2 +- .../README.nuget.md | 2 +- README.md | 56 +++++++++--------- SECURITY.md | 2 +- doc/FirstClassErrors.Documentation.csproj | 19 +++--- doc/generated/README.md | 12 ++++ doc/generated/gendoc/.gitkeep | 2 + .../AddingAReleaseTrain.en.md | 24 ++++---- .../AddingAReleaseTrain.fr.md | 24 ++++---- .../handwritten/for-maintainers}/README.fr.md | 6 +- .../handwritten/for-maintainers}/README.md | 6 +- .../for-maintainers}/ReleaseDryRun.en.md | 0 .../for-maintainers}/ReleaseDryRun.fr.md | 0 .../0001-lock-the-analyzer-roslyn-floor.fr.md | 2 +- .../0001-lock-the-analyzer-roslyn-floor.md | 2 +- .../adr/0002-floor-the-tooling-runtime.fr.md | 0 .../adr/0002-floor-the-tooling-runtime.md | 0 ...ify-outcome-value-mapping-under-then.fr.md | 0 ...-unify-outcome-value-mapping-under-then.md | 0 ...ry-pull-request-against-the-adr-base.fr.md | 2 +- ...every-pull-request-against-the-adr-base.md | 2 +- ...me-for-the-outcome-returning-variant.fr.md | 0 ...-name-for-the-outcome-returning-variant.md | 0 ...y-test-values-from-a-seedable-source.fr.md | 2 +- ...rary-test-values-from-a-seedable-source.md | 2 +- ...-the-binder-terminals-new-and-create.fr.md | 0 ...ame-the-binder-terminals-new-and-create.md | 0 ...s-through-a-struct-constrained-overload.md | 0 ...lings-failures-as-first-class-errors.fr.md | 0 ...toolings-failures-as-first-class-errors.md | 0 .../for-maintainers}/adr/README.md | 4 +- .../for-maintainers}/adr/template.md | 2 +- .../for-maintainers}/workflows/README.fr.md | 4 +- .../for-maintainers}/workflows/README.md | 4 +- .../workflows/adr-check.en.md | 12 ++-- .../workflows/adr-check.fr.md | 12 ++-- .../workflows/analyzers.en.md | 2 +- .../workflows/analyzers.fr.md | 2 +- .../workflows/changelog.en.md | 22 +++---- .../workflows/changelog.fr.md | 22 +++---- .../for-maintainers}/workflows/ci.en.md | 8 +-- .../for-maintainers}/workflows/ci.fr.md | 8 +-- .../for-maintainers}/workflows/codeql.en.md | 2 +- .../for-maintainers}/workflows/codeql.fr.md | 2 +- .../workflows/commit-lint.en.md | 8 +-- .../workflows/commit-lint.fr.md | 8 +-- .../workflows/dependabot-automerge.en.md | 6 +- .../workflows/dependabot-automerge.fr.md | 6 +- .../workflows/dependency-review.en.md | 4 +- .../workflows/dependency-review.fr.md | 4 +- .../workflows/release-dryrun.en.md | 2 +- .../workflows/release-dryrun.fr.md | 2 +- .../for-maintainers}/workflows/release.en.md | 2 +- .../for-maintainers}/workflows/release.fr.md | 2 +- .../workflows/scorecard.en.md | 2 +- .../workflows/scorecard.fr.md | 2 +- .../for-maintainers}/workflows/sonar.en.md | 2 +- .../for-maintainers}/workflows/sonar.fr.md | 2 +- .../for-users}/ArbitraryTestValues.en.md | 2 +- .../for-users}/ArbitraryTestValues.fr.md | 0 ...chitectureOfTheDocumentationPipeline.en.md | 2 +- ...chitectureOfTheDocumentationPipeline.fr.md | 0 .../for-users}/BestPractices.en.md | 2 +- .../for-users}/BestPractices.fr.md | 0 .../for-users}/CONTRIBUTING.fr.md | 6 +- .../for-users}/CatalogVersioning.en.md | 2 +- .../for-users}/CatalogVersioning.fr.md | 0 .../for-users}/CatalogVersioningCI.en.md | 2 +- .../for-users}/CatalogVersioningCI.fr.md | 0 .../CatalogVersioningReference.en.md | 2 +- .../CatalogVersioningReference.fr.md | 0 .../ComparisonWithOtherLibraries.en.md | 0 .../ComparisonWithOtherLibraries.fr.md | 0 .../for-users}/CoreConcepts.en.md | 2 +- .../for-users}/CoreConcepts.fr.md | 0 .../for-users}/DesignPrinciples.en.md | 2 +- .../for-users}/DesignPrinciples.fr.md | 0 .../for-users}/DeterministicTesting.en.md | 2 +- .../for-users}/DeterministicTesting.fr.md | 0 .../DocumentationExtractionReference.en.md | 2 +- .../DocumentationExtractionReference.fr.md | 0 .../for-users}/DocumentationMap.en.md | 2 +- .../for-users}/DocumentationMap.fr.md | 0 .../for-users}/ErrorContext.en.md | 2 +- .../for-users}/ErrorContext.fr.md | 0 .../for-users}/ErrorTaxonomy.en.md | 2 +- .../for-users}/ErrorTaxonomy.fr.md | 0 doc/{ => handwritten/for-users}/FAQ.en.md | 2 +- doc/{ => handwritten/for-users}/FAQ.fr.md | 0 .../for-users}/GettingStarted.en.md | 2 +- .../for-users}/GettingStarted.fr.md | 0 .../for-users}/Internationalisation.fr.md | 0 .../for-users}/Internationalization.en.md | 2 +- .../for-users}/LoggingIntegration.en.md | 2 +- .../for-users}/LoggingIntegration.fr.md | 0 .../for-users}/OperationalIntegration.en.md | 2 +- .../for-users}/OperationalIntegration.fr.md | 0 .../for-users}/OutcomeGuide.en.md | 2 +- .../for-users}/OutcomeGuide.fr.md | 0 doc/{ => handwritten/for-users}/README.fr.md | 4 +- .../for-users}/RequestBinder.en.md | 4 +- .../for-users}/RequestBinder.fr.md | 2 +- .../for-users}/SECURITY.fr.md | 2 +- doc/{ => handwritten/for-users}/Testing.en.md | 2 +- doc/{ => handwritten/for-users}/Testing.fr.md | 0 .../for-users}/TheHtmlRenderer.en.md | 0 .../for-users}/TheHtmlRenderer.fr.md | 0 .../for-users}/UsagePatterns.en.md | 2 +- .../for-users}/UsagePatterns.fr.md | 0 .../WhenNotToUseFirstClassErrors.en.md | 2 +- .../WhenNotToUseFirstClassErrors.fr.md | 0 .../for-users}/WritingACustomRenderer.en.md | 2 +- .../for-users}/WritingACustomRenderer.fr.md | 0 .../for-users}/WritingErrorMessages.en.md | 2 +- .../for-users}/WritingErrorMessages.fr.md | 0 .../for-users}/WritingErrorsGuide.en.md | 2 +- .../for-users}/WritingErrorsGuide.fr.md | 0 .../for-users}/analyzers/FCE001.en.md | 0 .../for-users}/analyzers/FCE001.fr.md | 0 .../for-users}/analyzers/FCE002.en.md | 0 .../for-users}/analyzers/FCE002.fr.md | 0 .../for-users}/analyzers/FCE003.en.md | 0 .../for-users}/analyzers/FCE003.fr.md | 0 .../for-users}/analyzers/FCE004.en.md | 0 .../for-users}/analyzers/FCE004.fr.md | 0 .../for-users}/analyzers/FCE005.en.md | 0 .../for-users}/analyzers/FCE005.fr.md | 0 .../for-users}/analyzers/FCE006.en.md | 0 .../for-users}/analyzers/FCE006.fr.md | 0 .../for-users}/analyzers/FCE007.en.md | 0 .../for-users}/analyzers/FCE007.fr.md | 0 .../for-users}/analyzers/FCE008.en.md | 0 .../for-users}/analyzers/FCE008.fr.md | 0 .../for-users}/analyzers/FCE009.en.md | 0 .../for-users}/analyzers/FCE009.fr.md | 0 .../for-users}/analyzers/FCE010.en.md | 0 .../for-users}/analyzers/FCE010.fr.md | 0 .../for-users}/analyzers/FCE011.en.md | 0 .../for-users}/analyzers/FCE011.fr.md | 0 .../for-users}/analyzers/FCE012.en.md | 0 .../for-users}/analyzers/FCE012.fr.md | 0 .../for-users}/analyzers/FCE013.en.md | 0 .../for-users}/analyzers/FCE013.fr.md | 0 .../for-users}/analyzers/FCE014.en.md | 0 .../for-users}/analyzers/FCE014.fr.md | 0 .../for-users}/analyzers/FCE015.en.md | 0 .../for-users}/analyzers/FCE015.fr.md | 0 .../for-users}/analyzers/FCE016.en.md | 0 .../for-users}/analyzers/FCE016.fr.md | 0 .../for-users}/analyzers/FCE017.en.md | 0 .../for-users}/analyzers/FCE017.fr.md | 0 .../for-users}/analyzers/FCE018.en.md | 0 .../for-users}/analyzers/FCE018.fr.md | 0 .../for-users}/analyzers/README.fr.md | 0 .../for-users}/analyzers/README.md | 0 .../for-users}/images/first-class-errors.png | Bin tools/adr-check/collect-context.sh | 2 +- tools/packaging/pack.sh | 2 +- tools/trains.sh | 2 +- 168 files changed, 228 insertions(+), 209 deletions(-) create mode 100644 doc/generated/README.md create mode 100644 doc/generated/gendoc/.gitkeep rename {maintainers => doc/handwritten/for-maintainers}/AddingAReleaseTrain.en.md (80%) rename {maintainers => doc/handwritten/for-maintainers}/AddingAReleaseTrain.fr.md (82%) rename {maintainers => doc/handwritten/for-maintainers}/README.fr.md (90%) rename {maintainers => doc/handwritten/for-maintainers}/README.md (89%) rename {maintainers => doc/handwritten/for-maintainers}/ReleaseDryRun.en.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/ReleaseDryRun.fr.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0001-lock-the-analyzer-roslyn-floor.fr.md (99%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0001-lock-the-analyzer-roslyn-floor.md (98%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0002-floor-the-tooling-runtime.fr.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0002-floor-the-tooling-runtime.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0003-unify-outcome-value-mapping-under-then.fr.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0003-unify-outcome-value-mapping-under-then.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0004-check-every-pull-request-against-the-adr-base.fr.md (99%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0004-check-every-pull-request-against-the-adr-base.md (98%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.fr.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md (99%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md (98%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0007-name-the-binder-terminals-new-and-create.fr.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0007-name-the-binder-terminals-new-and-create.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0009-report-the-toolings-failures-as-first-class-errors.fr.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/0009-report-the-toolings-failures-as-first-class-errors.md (100%) rename {maintainers => doc/handwritten/for-maintainers}/adr/README.md (97%) rename {maintainers => doc/handwritten/for-maintainers}/adr/template.md (97%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/README.fr.md (97%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/README.md (96%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/adr-check.en.md (90%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/adr-check.fr.md (92%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/analyzers.en.md (98%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/analyzers.fr.md (99%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/changelog.en.md (90%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/changelog.fr.md (92%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/ci.en.md (93%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/ci.fr.md (94%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/codeql.en.md (96%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/codeql.fr.md (98%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/commit-lint.en.md (87%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/commit-lint.fr.md (87%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/dependabot-automerge.en.md (91%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/dependabot-automerge.fr.md (92%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/dependency-review.en.md (94%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/dependency-review.fr.md (94%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/release-dryrun.en.md (98%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/release-dryrun.fr.md (98%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/release.en.md (98%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/release.fr.md (99%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/scorecard.en.md (97%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/scorecard.fr.md (99%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/sonar.en.md (96%) rename {maintainers => doc/handwritten/for-maintainers}/workflows/sonar.fr.md (98%) rename doc/{ => handwritten/for-users}/ArbitraryTestValues.en.md (97%) rename doc/{ => handwritten/for-users}/ArbitraryTestValues.fr.md (100%) rename doc/{ => handwritten/for-users}/ArchitectureOfTheDocumentationPipeline.en.md (97%) rename doc/{ => handwritten/for-users}/ArchitectureOfTheDocumentationPipeline.fr.md (100%) rename doc/{ => handwritten/for-users}/BestPractices.en.md (97%) rename doc/{ => handwritten/for-users}/BestPractices.fr.md (100%) rename doc/{ => handwritten/for-users}/CONTRIBUTING.fr.md (99%) rename doc/{ => handwritten/for-users}/CatalogVersioning.en.md (97%) rename doc/{ => handwritten/for-users}/CatalogVersioning.fr.md (100%) rename doc/{ => handwritten/for-users}/CatalogVersioningCI.en.md (97%) rename doc/{ => handwritten/for-users}/CatalogVersioningCI.fr.md (100%) rename doc/{ => handwritten/for-users}/CatalogVersioningReference.en.md (97%) rename doc/{ => handwritten/for-users}/CatalogVersioningReference.fr.md (100%) rename doc/{ => handwritten/for-users}/ComparisonWithOtherLibraries.en.md (100%) rename doc/{ => handwritten/for-users}/ComparisonWithOtherLibraries.fr.md (100%) rename doc/{ => handwritten/for-users}/CoreConcepts.en.md (96%) rename doc/{ => handwritten/for-users}/CoreConcepts.fr.md (100%) rename doc/{ => handwritten/for-users}/DesignPrinciples.en.md (96%) rename doc/{ => handwritten/for-users}/DesignPrinciples.fr.md (100%) rename doc/{ => handwritten/for-users}/DeterministicTesting.en.md (98%) rename doc/{ => handwritten/for-users}/DeterministicTesting.fr.md (100%) rename doc/{ => handwritten/for-users}/DocumentationExtractionReference.en.md (98%) rename doc/{ => handwritten/for-users}/DocumentationExtractionReference.fr.md (100%) rename doc/{ => handwritten/for-users}/DocumentationMap.en.md (98%) rename doc/{ => handwritten/for-users}/DocumentationMap.fr.md (100%) rename doc/{ => handwritten/for-users}/ErrorContext.en.md (98%) rename doc/{ => handwritten/for-users}/ErrorContext.fr.md (100%) rename doc/{ => handwritten/for-users}/ErrorTaxonomy.en.md (98%) rename doc/{ => handwritten/for-users}/ErrorTaxonomy.fr.md (100%) rename doc/{ => handwritten/for-users}/FAQ.en.md (99%) rename doc/{ => handwritten/for-users}/FAQ.fr.md (100%) rename doc/{ => handwritten/for-users}/GettingStarted.en.md (98%) rename doc/{ => handwritten/for-users}/GettingStarted.fr.md (100%) rename doc/{ => handwritten/for-users}/Internationalisation.fr.md (100%) rename doc/{ => handwritten/for-users}/Internationalization.en.md (98%) rename doc/{ => handwritten/for-users}/LoggingIntegration.en.md (98%) rename doc/{ => handwritten/for-users}/LoggingIntegration.fr.md (100%) rename doc/{ => handwritten/for-users}/OperationalIntegration.en.md (98%) rename doc/{ => handwritten/for-users}/OperationalIntegration.fr.md (100%) rename doc/{ => handwritten/for-users}/OutcomeGuide.en.md (98%) rename doc/{ => handwritten/for-users}/OutcomeGuide.fr.md (100%) rename doc/{ => handwritten/for-users}/README.fr.md (97%) rename doc/{ => handwritten/for-users}/RequestBinder.en.md (99%) rename doc/{ => handwritten/for-users}/RequestBinder.fr.md (99%) rename doc/{ => handwritten/for-users}/SECURITY.fr.md (98%) rename doc/{ => handwritten/for-users}/Testing.en.md (97%) rename doc/{ => handwritten/for-users}/Testing.fr.md (100%) rename doc/{ => handwritten/for-users}/TheHtmlRenderer.en.md (100%) rename doc/{ => handwritten/for-users}/TheHtmlRenderer.fr.md (100%) rename doc/{ => handwritten/for-users}/UsagePatterns.en.md (98%) rename doc/{ => handwritten/for-users}/UsagePatterns.fr.md (100%) rename doc/{ => handwritten/for-users}/WhenNotToUseFirstClassErrors.en.md (94%) rename doc/{ => handwritten/for-users}/WhenNotToUseFirstClassErrors.fr.md (100%) rename doc/{ => handwritten/for-users}/WritingACustomRenderer.en.md (98%) rename doc/{ => handwritten/for-users}/WritingACustomRenderer.fr.md (100%) rename doc/{ => handwritten/for-users}/WritingErrorMessages.en.md (98%) rename doc/{ => handwritten/for-users}/WritingErrorMessages.fr.md (100%) rename doc/{ => handwritten/for-users}/WritingErrorsGuide.en.md (98%) rename doc/{ => handwritten/for-users}/WritingErrorsGuide.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE001.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE001.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE002.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE002.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE003.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE003.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE004.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE004.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE005.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE005.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE006.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE006.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE007.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE007.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE008.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE008.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE009.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE009.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE010.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE010.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE011.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE011.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE012.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE012.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE013.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE013.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE014.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE014.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE015.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE015.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE016.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE016.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE017.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE017.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE018.en.md (100%) rename doc/{ => handwritten/for-users}/analyzers/FCE018.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/README.fr.md (100%) rename doc/{ => handwritten/for-users}/analyzers/README.md (100%) rename doc/{ => handwritten/for-users}/images/first-class-errors.png (100%) diff --git a/.github/adr-check-prompt.md b/.github/adr-check-prompt.md index 1b336ae..ce72eed 100644 --- a/.github/adr-check-prompt.md +++ b/.github/adr-check-prompt.md @@ -73,7 +73,7 @@ Rules: - Base every claim strictly on the provided data. **Invent nothing.** Do not guess an ADR number — only cite an ADR that appears in the ADR base. - The `report` is **advisory**. It must make clear that nothing here blocks a - merge, that a human or an agent drafts the ADR(s) under `maintainers/adr/` with + merge, that a human or an agent drafts the ADR(s) under `doc/handwritten/for-maintainers/adr/` with `Status: Proposed`, and that the maintainer accepts, supersedes, or deprecates. Never claim to have written an ADR or to block anything. @@ -95,6 +95,6 @@ nothing here blocks a merge. **Conflicts with** - ⚠️ ADR-NNNN () — <the contradiction> -_Agents: draft the ADR(s) under `maintainers/adr/` as `Status: Proposed` and link +_Agents: draft the ADR(s) under `doc/handwritten/for-maintainers/adr/` as `Status: Proposed` and link them; the maintainer decides. See `AGENTS.md` → "Architecture decisions"._ ``` diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7bfab97..a032169 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -47,14 +47,14 @@ * [ ] Public API / error documentation updated * [ ] README / `doc/` updated -* [ ] French translation (`doc/README.fr.md`) updated if user-facing behavior changed +* [ ] French translation (`doc/handwritten/for-users/README.fr.md`) updated if user-facing behavior changed * [ ] No documentation change required ## Architecture decisions -<!-- Every pull request is checked against the ADR base (maintainers/adr/). Most +<!-- Every pull request is checked against the ADR base (doc/handwritten/for-maintainers/adr/). Most embark no architectural decision — tick the first box. Agents draft ADRs as - `Proposed`; the maintainer accepts or supersedes. See maintainers/adr/README.md. --> + `Proposed`; the maintainer accepts or supersedes. See doc/handwritten/for-maintainers/adr/README.md. --> * [ ] No architectural decision in this pull request * [ ] New decision recorded — ADR drafted as `Proposed`: ADR-____ diff --git a/.github/workflows/adr-check.yml b/.github/workflows/adr-check.yml index 6e19876..4ea0da4 100644 --- a/.github/workflows/adr-check.yml +++ b/.github/workflows/adr-check.yml @@ -10,7 +10,7 @@ name: adr-check # recording a decision is a human-reviewed act, exactly like the sibling # `changelog` workflow. It NEVER blocks anything and NEVER writes an ADR — every # failure mode is a warning, and the verdict is a recommendation a human acts on. -# See maintainers/workflows/adr-check.en.md. +# See doc/handwritten/for-maintainers/workflows/adr-check.en.md. on: workflow_dispatch: inputs: diff --git a/.github/workflows/canary.yml b/.github/workflows/canary.yml index 4691126..53c6e40 100644 --- a/.github/workflows/canary.yml +++ b/.github/workflows/canary.yml @@ -3,7 +3,7 @@ name: canary # Early-warning that the documentation tooling still runs on the NEXT, not-yet-released .NET. # # The shipped tooling targets net8.0 and reaches every newer runtime purely by roll-forward (the worker uses -# LatestMajor; see maintainers/adr/0002-floor-the-tooling-runtime.md). A runtime breaking change in a future +# LatestMajor; see doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.md). A runtime breaking change in a future # major would surface here first — on a schedule, against the current preview — instead of in a user's CI the # day that major ships. It is the upper-end counterpart of the `floor` job in ci.yml, which pins the lower end. # diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6d9c7f3..33d986a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -72,7 +72,7 @@ jobs: # build-test above runs the whole suite on the LATEST .NET (10). This job proves the other end of the # supported range: that the fce tool and its worker, which ship targeting net8.0 (the floor — see - # maintainers/adr/0002-floor-the-tooling-runtime.md), actually run on the .NET 8 RUNTIME. The net8 TFM + # doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.md), actually run on the .NET 8 RUNTIME. The net8 TFM # already guards the compile-time API surface on every build; what it cannot show is that the tooling # executes on its advertised minimum runtime, which is what this job checks against the real artifacts. floor: diff --git a/AGENTS.md b/AGENTS.md index 8492e7e..d3289be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ Two roles are covered: **writing code** and **reviewing pull requests**. - Build: `dotnet build FirstClassErrors.sln` - Test: `dotnet test FirstClassErrors.sln` (analyzer tests: `dotnet test FirstClassErrors.Analyzers.UnitTests`). - Repository language is **English** (code, comments, commits, PRs, issues, and - review comments). French lives only in `doc/README.fr.md` and must stay in sync + review comments). French lives only in `doc/handwritten/for-users/README.fr.md` and must stay in sync with the English README. - `Error` and its hierarchy, `ErrorCode`, `ErrorContextKey`, `Outcome`/`Outcome<T>` and any value object are **`class`, never `struct`** — a struct exposes a @@ -21,7 +21,7 @@ Two roles are covered: **writing code** and **reviewing pull requests**. ## Architecture decisions (code changes) Before finalizing a pull request, check it against the ADR base under -`maintainers/adr/` (format and conventions: `maintainers/adr/README.md`). An ADR +`doc/handwritten/for-maintainers/adr/` (format and conventions: `doc/handwritten/for-maintainers/adr/README.md`). An ADR records a **significant, lasting decision** — one a future maintainer would ask "why did they do it this way?" about — not every change. Apply the README's test: *if the implementation changed but the decision stood, the ADR should not need diff --git a/CLAUDE.md b/CLAUDE.md index 2f1ff3b..c8560f4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,7 +10,7 @@ errors should stay structured, documented, and close to the code. source code, code comments, commit messages, branch names, PR titles and descriptions, and issues. * The English documentation is canonical. -* The French documentation in `doc/README.fr.md` is an intentional translation +* The French documentation in `doc/handwritten/for-users/README.fr.md` is an intentional translation and must stay in sync with the English documentation when user-facing behavior changes. * You may reply to me in French in the chat, but never write repository content in French unless you are updating the French documentation. @@ -34,7 +34,7 @@ errors should stay structured, documented, and close to the code. * `FirstClassErrors.Cli` — command-line tool * `FirstClassErrors.RequestBinder` — request binder for the primary-adapter boundary (+ `.UnitTests`) * `FirstClassErrors.Usage` — usage examples -* `doc/` — documentation, including the French translation +* `doc/` — documentation: `handwritten/` (`for-users`, `for-maintainers`) and `generated/` (CI/CD living docs) ## Change guidelines @@ -62,16 +62,16 @@ errors should stay structured, documented, and close to the code. * When you add or change an error, update its documentation accordingly. * When you change user-facing behavior, keep the English README and the French translation - (`doc/README.fr.md`) in sync. + (`doc/handwritten/for-users/README.fr.md`) in sync. * When you change analyzers, update or add analyzer tests. * When you change diagnostics, keep diagnostic IDs, messages, documentation, and tests consistent. ## Architecture decisions (ADRs) Before finalizing a pull request, check the change against the ADR base under -`maintainers/adr/`. This is **advisory**: produce a recommendation, never a +`doc/handwritten/for-maintainers/adr/`. This is **advisory**: produce a recommendation, never a blocker. Full procedure in [`AGENTS.md`](AGENTS.md) ("Architecture decisions"); -format and conventions in [`maintainers/adr/README.md`](maintainers/adr/README.md). +format and conventions in [`doc/handwritten/for-maintainers/adr/README.md`](doc/handwritten/for-maintainers/adr/README.md). The essentials, inlined so they hold even if `AGENTS.md` is not read: * An ADR records a **significant, lasting decision** — one a future maintainer diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55e9e6f..f450643 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing to FirstClassErrors 🌍 **Languages:** -🇬🇧 English (this file) | 🇫🇷 [Français](./doc/CONTRIBUTING.fr.md) +🇬🇧 English (this file) | 🇫🇷 [Français](doc/handwritten/for-users/CONTRIBUTING.fr.md) FirstClassErrors treats errors as first-class, documented, diagnosable concepts. The history of the repository should be as legible as the errors the @@ -473,7 +473,7 @@ Ordered as the rules are: type, scope, description, body, breaking, issue. ### Adoption This guide is the rule for commits in this repository. Deviating from it -requires a justification — an ADR under `maintainers/adr/`, or an update to this +requires a justification — an ADR under `doc/handwritten/for-maintainers/adr/`, or an update to this guide. It applies from its adoption on, to every commit created after. Prior history is diff --git a/FirstClassErrors.Analyzers/HelpLinks.cs b/FirstClassErrors.Analyzers/HelpLinks.cs index 651f3a4..0d997f5 100644 --- a/FirstClassErrors.Analyzers/HelpLinks.cs +++ b/FirstClassErrors.Analyzers/HelpLinks.cs @@ -2,11 +2,11 @@ namespace FirstClassErrors.Analyzers; /// <summary> /// Builds the documentation URL surfaced by each diagnostic (the "help link" in the IDE). Per-rule pages are added -/// under <c>doc/analyzers/</c> in a later phase. +/// under <c>doc/handwritten/for-users/analyzers/</c> in a later phase. /// </summary> internal static class HelpLinks { - private const string Base = "https://github.com/Reefact/first-class-errors/blob/main/doc/analyzers"; + private const string Base = "https://github.com/Reefact/first-class-errors/blob/main/doc/handwritten/for-users/analyzers"; public static string For(string diagnosticId) { return $"{Base}/{diagnosticId}.en.md"; diff --git a/FirstClassErrors.Cli/FirstClassErrors.Cli.csproj b/FirstClassErrors.Cli/FirstClassErrors.Cli.csproj index 59c93a8..e71513c 100644 --- a/FirstClassErrors.Cli/FirstClassErrors.Cli.csproj +++ b/FirstClassErrors.Cli/FirstClassErrors.Cli.csproj @@ -110,7 +110,7 @@ Do NOT rely on `dotnet build` or `dotnet publish` to validate that the tool ships its worker: neither exercises the .nupkg content, so both stay green even if the worker never reaches the package. The real gates are the worker-present assertion in tools/packaging/pack.sh and the manual tool-install smoke test documented in - maintainers/ReleaseDryRun (install the packed tool, run `fce generate`, expect a non-empty catalog). --> + doc/handwritten/for-maintainers/ReleaseDryRun (install the packed tool, run `fce generate`, expect a non-empty catalog). --> <Target Name="_CopyDocumentationWorker" AfterTargets="Build"> <ItemGroup> <_DocumentationWorkerFiles Include="$(MSBuildThisFileDirectory)..\FirstClassErrors.GenDoc.Worker\bin\$(Configuration)\$(TargetFramework)\**\*.*" /> diff --git a/FirstClassErrors.RequestBinder/README.nuget.md b/FirstClassErrors.RequestBinder/README.nuget.md index ed368ba..6fc6178 100644 --- a/FirstClassErrors.RequestBinder/README.nuget.md +++ b/FirstClassErrors.RequestBinder/README.nuget.md @@ -17,4 +17,4 @@ Outcome<PlaceBookingCommand> command = bind.New(s => new PlaceBookingCommand(s.Get(email), s.Get(stay))); ``` -See the [request-binder guide](https://github.com/Reefact/first-class-errors/blob/main/doc/RequestBinder.en.md) for the full walkthrough, and the [repository documentation](https://github.com/Reefact/first-class-errors) for the rest of FirstClassErrors. +See the [request-binder guide](https://github.com/Reefact/first-class-errors/blob/main/doc/handwritten/for-users/RequestBinder.en.md) for the full walkthrough, and the [repository documentation](https://github.com/Reefact/first-class-errors) for the rest of FirstClassErrors. diff --git a/README.md b/README.md index fdb933a..e6c1ba7 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # FirstClassErrors 🌍 **Languages:** -🇬🇧 English (this file) | 🇫🇷 [Français](./doc/README.fr.md) +🇬🇧 English (this file) | 🇫🇷 [Français](doc/handwritten/for-users/README.fr.md) | | | | :-- | :-- | @@ -15,7 +15,7 @@ **Turn your errors into structured, living knowledge about your system.** -![FirstClassErrors](./doc/images/first-class-errors.png "FirstClassErrors") +![FirstClassErrors](doc/handwritten/for-users/images/first-class-errors.png "FirstClassErrors") ## 🚨 The problem @@ -124,7 +124,7 @@ To generate documentation, install the CLI: dotnet tool install --global FirstClassErrors.Cli ``` -Then follow the [Getting Started guide](doc/GettingStarted.en.md) to create and generate your first documented error. +Then follow the [Getting Started guide](doc/handwritten/for-users/GettingStarted.en.md) to create and generate your first documented error. ## 🎯 When it is a good fit @@ -135,11 +135,11 @@ FirstClassErrors is especially useful for long-lived application or domain code - support and operations investigate production failures; - documentation must remain aligned with behavior. -For prototypes, tiny utilities, or low-level technical code, standard exceptions may be enough. See [When Not to Use FirstClassErrors](doc/WhenNotToUseFirstClassErrors.en.md). +For prototypes, tiny utilities, or low-level technical code, standard exceptions may be enough. See [When Not to Use FirstClassErrors](doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md). ## 🔍 Analyzers and supply-chain information -The package includes Roslyn rules with stable `FCExxx` identifiers. They detect duplicate or malformed error codes, invalid documentation wiring, missing examples, and common API misuse. See the [analyzer rules reference](doc/analyzers/README.md). +The package includes Roslyn rules with stable `FCExxx` identifiers. They detect duplicate or malformed error codes, invalid documentation wiring, missing examples, and common API misuse. See the [analyzer rules reference](doc/handwritten/for-users/analyzers/README.md). Released packages include signed build provenance and an embedded SPDX SBOM. See the release and verification details in the [supply-chain documentation](SECURITY.md). @@ -153,39 +153,39 @@ For security vulnerabilities, follow the private process in [SECURITY.md](SECURI ### Discover -- [Getting Started](doc/GettingStarted.en.md) -- [Design Principles](doc/DesignPrinciples.en.md) -- [When Not to Use FirstClassErrors](doc/WhenNotToUseFirstClassErrors.en.md) +- [Getting Started](doc/handwritten/for-users/GettingStarted.en.md) +- [Design Principles](doc/handwritten/for-users/DesignPrinciples.en.md) +- [When Not to Use FirstClassErrors](doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md) ### Understand the model -- [Core Concepts](doc/CoreConcepts.en.md) -- [Error Taxonomy and Composition](doc/ErrorTaxonomy.en.md) -- [Error Context Guide](doc/ErrorContext.en.md) +- [Core Concepts](doc/handwritten/for-users/CoreConcepts.en.md) +- [Error Taxonomy and Composition](doc/handwritten/for-users/ErrorTaxonomy.en.md) +- [Error Context Guide](doc/handwritten/for-users/ErrorContext.en.md) ### Write and use errors -- [Writing Errors Guide](doc/WritingErrorsGuide.en.md) -- [Usage Patterns](doc/UsagePatterns.en.md) -- [Binding requests at the boundary (RequestBinder)](doc/RequestBinder.en.md) -- [Best Practices](doc/BestPractices.en.md) -- [Testing Guide](doc/Testing.en.md) - - [Deterministic Error Tests](doc/DeterministicTesting.en.md) - - [Arbitrary Test Values](doc/ArbitraryTestValues.en.md) +- [Writing Errors Guide](doc/handwritten/for-users/WritingErrorsGuide.en.md) +- [Usage Patterns](doc/handwritten/for-users/UsagePatterns.en.md) +- [Binding requests at the boundary (RequestBinder)](doc/handwritten/for-users/RequestBinder.en.md) +- [Best Practices](doc/handwritten/for-users/BestPractices.en.md) +- [Testing Guide](doc/handwritten/for-users/Testing.en.md) + - [Deterministic Error Tests](doc/handwritten/for-users/DeterministicTesting.en.md) + - [Arbitrary Test Values](doc/handwritten/for-users/ArbitraryTestValues.en.md) ### Generate and operate the catalog -- [CI/CD and Operational Integration](doc/OperationalIntegration.en.md) +- [CI/CD and Operational Integration](doc/handwritten/for-users/OperationalIntegration.en.md) - Catalog versioning - - [Overview and workflow](doc/CatalogVersioning.en.md) - - [Command reference](doc/CatalogVersioningReference.en.md) - - [CI/CD integration](doc/CatalogVersioningCI.en.md) -- [Architecture of the Documentation Pipeline](doc/ArchitectureOfTheDocumentationPipeline.en.md) -- [Writing a custom renderer](doc/WritingACustomRenderer.en.md) -- [Internationalization](doc/Internationalization.en.md) + - [Overview and workflow](doc/handwritten/for-users/CatalogVersioning.en.md) + - [Command reference](doc/handwritten/for-users/CatalogVersioningReference.en.md) + - [CI/CD integration](doc/handwritten/for-users/CatalogVersioningCI.en.md) +- [Architecture of the Documentation Pipeline](doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md) +- [Writing a custom renderer](doc/handwritten/for-users/WritingACustomRenderer.en.md) +- [Internationalization](doc/handwritten/for-users/Internationalization.en.md) ### Evaluate and troubleshoot -- [Comparison with error-handling libraries](doc/ComparisonWithOtherLibraries.en.md) -- [Analyzer rules (FCExxx)](doc/analyzers/README.md) -- [FAQ](doc/FAQ.en.md) +- [Comparison with error-handling libraries](doc/handwritten/for-users/ComparisonWithOtherLibraries.en.md) +- [Analyzer rules (FCExxx)](doc/handwritten/for-users/analyzers/README.md) +- [FAQ](doc/handwritten/for-users/FAQ.en.md) diff --git a/SECURITY.md b/SECURITY.md index 5155486..277c934 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,7 +1,7 @@ # Security Policy 🌍 **Languages:** -🇬🇧 English (this file) | 🇫🇷 [Français](./doc/SECURITY.fr.md) +🇬🇧 English (this file) | 🇫🇷 [Français](doc/handwritten/for-users/SECURITY.fr.md) ## Supported Versions diff --git a/doc/FirstClassErrors.Documentation.csproj b/doc/FirstClassErrors.Documentation.csproj index b7c492f..cb666b9 100644 --- a/doc/FirstClassErrors.Documentation.csproj +++ b/doc/FirstClassErrors.Documentation.csproj @@ -3,11 +3,15 @@ <!-- Documentation-only project. - This project compiles nothing. Its sole purpose is to surface everything - under doc/ in the Visual Studio Solution Explorer, so the documentation is - easy to find, read and edit right next to the code: the Markdown pages - (English *.en.md and French *.fr.md, including the analyzer pages under - analyzers/), the images, and any other asset that may be added later. + This project compiles nothing. Its sole purpose is to surface every piece of + documentation under doc/ in the Visual Studio Solution Explorer, so it is + easy to find, read and edit right next to the code. It covers the whole tree: + + doc/generated/ - living documentation produced by CI/CD (e.g. GenDoc) + doc/handwritten/ - documentation written by hand + for-users/ the library's user documentation (English *.en.md and + French *.fr.md, including the analyzer pages and images) + for-maintainers/ the maintainer documentation (ADRs, workflow notes, ...) The <None> glob below picks up new files automatically: no need to touch this project or the solution when documentation is added or renamed. The @@ -45,10 +49,11 @@ <!-- The repository's main README lives at the solution root, outside doc/, so the glob above cannot reach it. Reference it as a link so it is browsable - from this project too. Link metadata is required for files located outside + from this project too, placed next to its French translation under + handwritten/for-users. Link metadata is required for files located outside the project directory. --> - <None Include="..\README.md" Link="README.md" /> + <None Include="..\README.md" Link="handwritten\for-users\README.md" /> </ItemGroup> </Project> diff --git a/doc/generated/README.md b/doc/generated/README.md new file mode 100644 index 0000000..3f1f7db --- /dev/null +++ b/doc/generated/README.md @@ -0,0 +1,12 @@ +# Generated documentation + +This folder holds **living documentation produced automatically by CI/CD**. +Do not edit its contents by hand: anything here is regenerated (and overwritten) +on the next generation run. + +- [`gendoc/`](gendoc) — error catalog emitted by the GenDoc toolchain + (`FirstClassErrors.GenDoc` / `fce generate`). + +Handwritten documentation lives under [`../handwritten`](../handwritten): +[`for-users`](../handwritten/for-users) and +[`for-maintainers`](../handwritten/for-maintainers). diff --git a/doc/generated/gendoc/.gitkeep b/doc/generated/gendoc/.gitkeep new file mode 100644 index 0000000..6889834 --- /dev/null +++ b/doc/generated/gendoc/.gitkeep @@ -0,0 +1,2 @@ +# Placeholder so the CI/CD output directory is tracked before the first +# generation run. GenDoc writes the rendered error catalog here. diff --git a/maintainers/AddingAReleaseTrain.en.md b/doc/handwritten/for-maintainers/AddingAReleaseTrain.en.md similarity index 80% rename from maintainers/AddingAReleaseTrain.en.md rename to doc/handwritten/for-maintainers/AddingAReleaseTrain.en.md index e09382a..d1119ee 100644 --- a/maintainers/AddingAReleaseTrain.en.md +++ b/doc/handwritten/for-maintainers/AddingAReleaseTrain.en.md @@ -17,7 +17,7 @@ publishes on its own tag prefix. Today there are two: | `cli` | `cli-v*` | `cli`, `gendoc` | FirstClassErrors.Cli (the `fce` tool) | `FirstClassErrors.Cli/CHANGELOG.md` | The train → (prefix, scopes, package, changelog file) mapping lives in **one place**, -[`tools/trains.sh`](../tools/trains.sh), which the release-notes generator, the +[`tools/trains.sh`](../../../tools/trains.sh), which the release-notes generator, the changelog collector, and the changelog workflow all *source*. The rest of the edits below exist only because GitHub workflow triggers and choice inputs, the commit-lint scope allowlist, and the packing logic **cannot** be data-driven from that file — @@ -30,7 +30,7 @@ they are static by nature. ## The one data edit -**1. Add a row to [`tools/trains.sh`](../tools/trains.sh).** One line, pipe-separated: +**1. Add a row to [`tools/trains.sh`](../../../tools/trains.sh).** One line, pipe-separated: ``` <id>|<tag-prefix>|<scopes csv>|<changelog file>|<package label> @@ -44,12 +44,12 @@ The scopes must be a subset of the commit-lint allowlist (next step). ## The static edits GitHub and the tooling force **2. Commit scopes** — if the train introduces new scopes, add them to the closed -list in [`tools/commit-lint/lint-commit-message.sh`](../tools/commit-lint/lint-commit-message.sh) +list in [`tools/commit-lint/lint-commit-message.sh`](../../../tools/commit-lint/lint-commit-message.sh) (`SCOPES` **and** `SCOPES_HUMAN`) and to the scope table in -[`CONTRIBUTING.md`](../CONTRIBUTING.md). Without this, commits for the new component +[`CONTRIBUTING.md`](../../../CONTRIBUTING.md). Without this, commits for the new component fail the commit-lint check. -**3. [`.github/workflows/release.yml`](../.github/workflows/release.yml)** — three +**3. [`.github/workflows/release.yml`](../../../.github/workflows/release.yml)** — three spots: - the tag trigger list: add `- '<prefix>*.*.*'` (e.g. `- 'docs-v*.*.*'`); - the `component` `workflow_dispatch` choice: add `- <id>`; @@ -57,26 +57,26 @@ spots: `<prefix>*) COMPONENT="<id>"; VERSION="${REF_NAME#<prefix>}" ;;`, and add `<id>` to the `lib|cli)` allowlist `case` just below it. -**4. [`tools/packaging/pack.sh`](../tools/packaging/pack.sh)** — add a `<id>)` branch +**4. [`tools/packaging/pack.sh`](../../../tools/packaging/pack.sh)** — add a `<id>)` branch selecting which projects that train packs. This is genuinely train-specific packing logic (which `.csproj` to pack, whether a symbol package ships), so it is not driven from `trains.sh`. -**5. [`.github/workflows/release-dryrun.yml`](../.github/workflows/release-dryrun.yml)** — +**5. [`.github/workflows/release-dryrun.yml`](../../../.github/workflows/release-dryrun.yml)** — both rehearsal steps hardcode the train list: add `tools/packaging/pack.sh "$DRYRUN_VERSION" <id>` to the *Pack with SBOM* step and `tools/packaging/release-notes.sh <id> HEAD` to the *Rehearse release notes* step. Without this the new train's packaging and notes are never exercised before a real release — nothing fails, they are simply never run, which defeats the dry-run's whole purpose. -**6. [`.github/workflows/changelog.yml`](../.github/workflows/changelog.yml)** — add +**6. [`.github/workflows/changelog.yml`](../../../.github/workflows/changelog.yml)** — add `- <id>` to the `component` `workflow_dispatch` choice `options`. (The workflow reads everything else about the train from `trains.sh`.) ## What happens on its own -- [`tools/packaging/release-notes.sh`](../tools/packaging/release-notes.sh), - [`tools/changelog/collect-prs.sh`](../tools/changelog/collect-prs.sh), and the +- [`tools/packaging/release-notes.sh`](../../../tools/packaging/release-notes.sh), + [`tools/changelog/collect-prs.sh`](../../../tools/changelog/collect-prs.sh), and the changelog workflow's "Resolve component" step read the new row directly — no edit. - The train's **changelog file is created on the first drafting run** (`merge-unreleased.sh` lays down the Keep a Changelog preamble if the file is @@ -99,8 +99,8 @@ everything else about the train from `trains.sh`.) ## Related -- [`tools/trains.sh`](../tools/trains.sh) — the single source of truth this runbook +- [`tools/trains.sh`](../../../tools/trains.sh) — the single source of truth this runbook is built around. - [`changelog`](workflows/changelog.en.md) and [`release`](workflows/release.en.md) workflow pages. -- [`CONTRIBUTING.md`](../CONTRIBUTING.md) — the Conventional Commit scopes. +- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) — the Conventional Commit scopes. diff --git a/maintainers/AddingAReleaseTrain.fr.md b/doc/handwritten/for-maintainers/AddingAReleaseTrain.fr.md similarity index 82% rename from maintainers/AddingAReleaseTrain.fr.md rename to doc/handwritten/for-maintainers/AddingAReleaseTrain.fr.md index 4167c18..5a3df6a 100644 --- a/maintainers/AddingAReleaseTrain.fr.md +++ b/doc/handwritten/for-maintainers/AddingAReleaseTrain.fr.md @@ -18,7 +18,7 @@ aujourd'hui : | `cli` | `cli-v*` | `cli`, `gendoc` | FirstClassErrors.Cli (l'outil `fce`) | `FirstClassErrors.Cli/CHANGELOG.md` | Le mapping train → (préfixe, scopes, paquet, fichier changelog) vit à **un seul -endroit**, [`tools/trains.sh`](../tools/trains.sh), que le générateur de notes de +endroit**, [`tools/trains.sh`](../../../tools/trains.sh), que le générateur de notes de release, le collecteur de changelog et le workflow changelog *sourcent* tous. Les autres édits ci-dessous n'existent que parce que les triggers et les entrées de choix des workflows GitHub, la liste fermée des scopes du commit-lint, et la logique @@ -33,7 +33,7 @@ nature. ## L'unique édit de données -**1. Ajoutez une ligne à [`tools/trains.sh`](../tools/trains.sh).** Une ligne, séparée +**1. Ajoutez une ligne à [`tools/trains.sh`](../../../tools/trains.sh).** Une ligne, séparée par des barres verticales : ``` @@ -49,12 +49,12 @@ autre changement. Les scopes doivent être un sous-ensemble de la liste du commi ## Les édits statiques imposés par GitHub et la tooling **2. Scopes de commit** — si le train introduit de nouveaux scopes, ajoutez-les à la -liste fermée de [`tools/commit-lint/lint-commit-message.sh`](../tools/commit-lint/lint-commit-message.sh) +liste fermée de [`tools/commit-lint/lint-commit-message.sh`](../../../tools/commit-lint/lint-commit-message.sh) (`SCOPES` **et** `SCOPES_HUMAN`) et au tableau des scopes de -[`CONTRIBUTING.md`](../CONTRIBUTING.md). Sans ça, les commits du nouveau composant +[`CONTRIBUTING.md`](../../../CONTRIBUTING.md). Sans ça, les commits du nouveau composant échouent au check commit-lint. -**3. [`.github/workflows/release.yml`](../.github/workflows/release.yml)** — trois +**3. [`.github/workflows/release.yml`](../../../.github/workflows/release.yml)** — trois endroits : - la liste des triggers de tag : ajoutez `- '<préfixe>*.*.*'` (p. ex. `- 'docs-v*.*.*'`) ; - le choix `component` du `workflow_dispatch` : ajoutez `- <id>` ; @@ -62,12 +62,12 @@ endroits : `<préfixe>*) COMPONENT="<id>"; VERSION="${REF_NAME#<préfixe>}" ;;`, et ajoutez `<id>` à la liste blanche `lib|cli)` du `case` juste en dessous. -**4. [`tools/packaging/pack.sh`](../tools/packaging/pack.sh)** — ajoutez une branche +**4. [`tools/packaging/pack.sh`](../../../tools/packaging/pack.sh)** — ajoutez une branche `<id>)` sélectionnant quels projets ce train packe. C'est une logique de packaging réellement spécifique au train (quel `.csproj` packer, si un package de symboles est livré), donc elle n'est pas pilotée par `trains.sh`. -**5. [`.github/workflows/release-dryrun.yml`](../.github/workflows/release-dryrun.yml)** — +**5. [`.github/workflows/release-dryrun.yml`](../../../.github/workflows/release-dryrun.yml)** — les deux étapes de répétition codent la liste des trains en dur : ajoutez `tools/packaging/pack.sh "$DRYRUN_VERSION" <id>` à l'étape *Pack with SBOM* et `tools/packaging/release-notes.sh <id> HEAD` à l'étape *Rehearse release notes*. @@ -75,14 +75,14 @@ Sans cela, le packaging et les notes du nouveau train ne sont jamais exercés av une vraie release — rien n'échoue, ils ne sont simplement jamais lancés, ce qui annule tout l'intérêt du dry-run. -**6. [`.github/workflows/changelog.yml`](../.github/workflows/changelog.yml)** — +**6. [`.github/workflows/changelog.yml`](../../../.github/workflows/changelog.yml)** — ajoutez `- <id>` aux `options` du choix `component` du `workflow_dispatch`. (Le workflow lit tout le reste du train depuis `trains.sh`.) ## Ce qui se fait tout seul -- [`tools/packaging/release-notes.sh`](../tools/packaging/release-notes.sh), - [`tools/changelog/collect-prs.sh`](../tools/changelog/collect-prs.sh) et l'étape +- [`tools/packaging/release-notes.sh`](../../../tools/packaging/release-notes.sh), + [`tools/changelog/collect-prs.sh`](../../../tools/changelog/collect-prs.sh) et l'étape « Resolve component » du workflow changelog lisent la nouvelle ligne directement — aucun édit. - Le **fichier changelog du train est créé au premier run de rédaction** @@ -107,8 +107,8 @@ workflow lit tout le reste du train depuis `trains.sh`.) ## En rapport -- [`tools/trains.sh`](../tools/trains.sh) — la source unique de vérité autour de +- [`tools/trains.sh`](../../../tools/trains.sh) — la source unique de vérité autour de laquelle ce runbook est construit. - Les pages des workflows [`changelog`](workflows/changelog.fr.md) et [`release`](workflows/release.fr.md). -- [`CONTRIBUTING.fr.md`](../doc/CONTRIBUTING.fr.md) — les scopes Conventional Commit. +- [`CONTRIBUTING.fr.md`](../for-users/CONTRIBUTING.fr.md) — les scopes Conventional Commit. diff --git a/maintainers/README.fr.md b/doc/handwritten/for-maintainers/README.fr.md similarity index 90% rename from maintainers/README.fr.md rename to doc/handwritten/for-maintainers/README.fr.md index d76c336..eec1cec 100644 --- a/maintainers/README.fr.md +++ b/doc/handwritten/for-maintainers/README.fr.md @@ -5,7 +5,7 @@ > Documentation pour les **mainteneurs et opérateurs** de FirstClassErrors — > comment le projet est construit, publié et maintenu en bonne santé. Elle ne > fait **pas** partie de la documentation utilisateur de la librairie, sous -> [`doc/`](../doc/). La version anglaise est canonique ; les pages françaises sont +> [`doc/`](../for-users/). La version anglaise est canonique ; les pages françaises sont > tenues à jour en parallèle. ## Sommaire @@ -30,7 +30,7 @@ ces workflows structurellement. Aussi en [anglais](ReleaseDryRun.en.md). ### [Ajouter un train de release](AddingAReleaseTrain.fr.md) La checklist pour ajouter un nouveau paquet versionné indépendamment : l'unique -édit de données dans [`tools/trains.sh`](../tools/trains.sh) et les édits statiques +édit de données dans [`tools/trains.sh`](../../../tools/trains.sh) et les édits statiques imposés par GitHub et la tooling (trigger de tag, options de choix, scopes du commit-lint, packaging). Aussi en [anglais](AddingAReleaseTrain.en.md). @@ -51,5 +51,5 @@ copier. *(En anglais uniquement.)* ## En rapport -- [`CONTRIBUTING.fr.md`](../doc/CONTRIBUTING.fr.md) — conventions de commit et de pull +- [`CONTRIBUTING.fr.md`](../for-users/CONTRIBUTING.fr.md) — conventions de commit et de pull request (imposées par le workflow [`commit-lint`](workflows/commit-lint.fr.md)). diff --git a/maintainers/README.md b/doc/handwritten/for-maintainers/README.md similarity index 89% rename from maintainers/README.md rename to doc/handwritten/for-maintainers/README.md index f041feb..0bfa181 100644 --- a/maintainers/README.md +++ b/doc/handwritten/for-maintainers/README.md @@ -4,7 +4,7 @@ > Documentation for **maintainers and operators** of FirstClassErrors — how the > project is built, released, and kept healthy. It is **not** part of the -> library's user documentation, which lives under [`doc/`](../doc/). The English +> library's user documentation, which lives under [`doc/`](../for-users/). The English > version is canonical; the French pages are kept in sync. ## Contents @@ -28,7 +28,7 @@ workflows structurally. Also in [French](ReleaseDryRun.fr.md). ### [Adding a release train](AddingAReleaseTrain.en.md) The checklist for adding a new independently-versioned package: the single data -edit in [`tools/trains.sh`](../tools/trains.sh) and the static edits GitHub and the +edit in [`tools/trains.sh`](../../../tools/trains.sh) and the static edits GitHub and the tooling force (tag trigger, choice options, commit-lint scopes, packing). Also in [French](AddingAReleaseTrain.fr.md). @@ -48,5 +48,5 @@ follows and provides a copy-ready [template](adr/template.md). *(English only.)* ## Related -- [`CONTRIBUTING.md`](../CONTRIBUTING.md) — commit and pull-request conventions +- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) — commit and pull-request conventions (enforced by the [`commit-lint`](workflows/commit-lint.en.md) workflow). diff --git a/maintainers/ReleaseDryRun.en.md b/doc/handwritten/for-maintainers/ReleaseDryRun.en.md similarity index 100% rename from maintainers/ReleaseDryRun.en.md rename to doc/handwritten/for-maintainers/ReleaseDryRun.en.md diff --git a/maintainers/ReleaseDryRun.fr.md b/doc/handwritten/for-maintainers/ReleaseDryRun.fr.md similarity index 100% rename from maintainers/ReleaseDryRun.fr.md rename to doc/handwritten/for-maintainers/ReleaseDryRun.fr.md diff --git a/maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md b/doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md similarity index 99% rename from maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md rename to doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md index 220eb98..85dfdbf 100644 --- a/maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md +++ b/doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md @@ -176,7 +176,7 @@ version de référence reste au floor. `tools/floor-check/global.json` imbriqué) vers le SDK dont le Roslyn correspond au nouveau floor. 3. Mettre à jour la note d'exigence de compilateur du README / - `doc/README.fr.md`. + `doc/handwritten/for-users/README.fr.md`. 4. Remplacer cet ADR (nouveau floor, nouveau SDK/IDE minimum). L'épinglage, le test unitaire et l'ignore Dependabot ne nécessitent aucun diff --git a/maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md b/doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md similarity index 98% rename from maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md rename to doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md index c32dade..a39b2fd 100644 --- a/maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md +++ b/doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md @@ -160,7 +160,7 @@ which can break while every reference version stays at the floor. 2. Update the floor SDK in `analyzers.yml` (`dotnet-version` and the nested `tools/floor-check/global.json`) to the SDK whose Roslyn matches the new floor. - 3. Update the README / `doc/README.fr.md` compiler-requirement note. + 3. Update the README / `doc/handwritten/for-users/README.fr.md` compiler-requirement note. 4. Supersede this ADR (new floor, new minimum SDK/IDE). The pin, the unit test and the Dependabot ignore need no change — they all diff --git a/maintainers/adr/0002-floor-the-tooling-runtime.fr.md b/doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.fr.md similarity index 100% rename from maintainers/adr/0002-floor-the-tooling-runtime.fr.md rename to doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.fr.md diff --git a/maintainers/adr/0002-floor-the-tooling-runtime.md b/doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.md similarity index 100% rename from maintainers/adr/0002-floor-the-tooling-runtime.md rename to doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.md diff --git a/maintainers/adr/0003-unify-outcome-value-mapping-under-then.fr.md b/doc/handwritten/for-maintainers/adr/0003-unify-outcome-value-mapping-under-then.fr.md similarity index 100% rename from maintainers/adr/0003-unify-outcome-value-mapping-under-then.fr.md rename to doc/handwritten/for-maintainers/adr/0003-unify-outcome-value-mapping-under-then.fr.md diff --git a/maintainers/adr/0003-unify-outcome-value-mapping-under-then.md b/doc/handwritten/for-maintainers/adr/0003-unify-outcome-value-mapping-under-then.md similarity index 100% rename from maintainers/adr/0003-unify-outcome-value-mapping-under-then.md rename to doc/handwritten/for-maintainers/adr/0003-unify-outcome-value-mapping-under-then.md diff --git a/maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md b/doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md similarity index 99% rename from maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md rename to doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md index 6e28456..c834d51 100644 --- a/maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md +++ b/doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md @@ -8,7 +8,7 @@ ## Contexte -Le dépôt consigne les décisions importantes sous forme d'ADR dans `maintainers/adr/`, +Le dépôt consigne les décisions importantes sous forme d'ADR dans `doc/handwritten/for-maintainers/adr/`, mais rien ne confronte un changement à cette base au moment où le changement est réalisé. C'est dans une pull request que les nouvelles décisions entrent dans la base de code : elle peut embarquer une décision qui n'est jamais consignée, remplacer une diff --git a/maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md b/doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md similarity index 98% rename from maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md rename to doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md index f954449..7223222 100644 --- a/maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md +++ b/doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md @@ -8,7 +8,7 @@ ## Context -The repository records significant decisions as ADRs under `maintainers/adr/`, but +The repository records significant decisions as ADRs under `doc/handwritten/for-maintainers/adr/`, but nothing confronts a change with that base at the moment the change is made. A pull request is where new decisions enter the codebase: it can embark a decision that is never recorded, replace a decision an existing ADR holds without saying so, or diff --git a/maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.fr.md b/doc/handwritten/for-maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.fr.md similarity index 100% rename from maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.fr.md rename to doc/handwritten/for-maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.fr.md diff --git a/maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.md b/doc/handwritten/for-maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.md similarity index 100% rename from maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.md rename to doc/handwritten/for-maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.md diff --git a/maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md b/doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md similarity index 99% rename from maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md rename to doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md index 415d885..f8adfc7 100644 --- a/maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md +++ b/doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md @@ -180,7 +180,7 @@ principal. ## Références -* `doc/ArbitraryTestValues.en.md` — le guide où la nouvelle surface est +* `doc/handwritten/for-users/ArbitraryTestValues.en.md` — le guide où la nouvelle surface est documentée. * ADR-0005 — décision de nommage antérieure dans le même esprit (un nom devrait annoncer ce que fait un appel) ; contexte seulement, pas un précédent pour ce diff --git a/maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md b/doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md similarity index 98% rename from maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md rename to doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md index d580568..71e8966 100644 --- a/maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md +++ b/doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md @@ -155,6 +155,6 @@ ship test-only surface in the main package. ## References -* `doc/ArbitraryTestValues.en.md` — the guide where the new surface is documented. +* `doc/handwritten/for-users/ArbitraryTestValues.en.md` — the guide where the new surface is documented. * ADR-0005 — prior naming decision in the same spirit (a name should announce what a call does); context only, not a precedent for this choice. diff --git a/maintainers/adr/0007-name-the-binder-terminals-new-and-create.fr.md b/doc/handwritten/for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.fr.md similarity index 100% rename from maintainers/adr/0007-name-the-binder-terminals-new-and-create.fr.md rename to doc/handwritten/for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.fr.md diff --git a/maintainers/adr/0007-name-the-binder-terminals-new-and-create.md b/doc/handwritten/for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.md similarity index 100% rename from maintainers/adr/0007-name-the-binder-terminals-new-and-create.md rename to doc/handwritten/for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.md diff --git a/maintainers/adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.md b/doc/handwritten/for-maintainers/adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.md similarity index 100% rename from maintainers/adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.md rename to doc/handwritten/for-maintainers/adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.md diff --git a/maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.fr.md b/doc/handwritten/for-maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.fr.md similarity index 100% rename from maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.fr.md rename to doc/handwritten/for-maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.fr.md diff --git a/maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.md b/doc/handwritten/for-maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.md similarity index 100% rename from maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.md rename to doc/handwritten/for-maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.md diff --git a/maintainers/adr/README.md b/doc/handwritten/for-maintainers/adr/README.md similarity index 97% rename from maintainers/adr/README.md rename to doc/handwritten/for-maintainers/adr/README.md index ed79960..032fa55 100644 --- a/maintainers/adr/README.md +++ b/doc/handwritten/for-maintainers/adr/README.md @@ -15,7 +15,7 @@ the implementation changed but the decision stood, the ADR should not need editing.* A new decision is **recorded** here, a decision that replaces another is written as a **superseding** ADR, and a change that **conflicts** with an accepted ADR is raised for the maintainer. The agent procedure — draft as *Proposed*, never -flip a status unilaterally — is in [`AGENTS.md`](../../AGENTS.md). +flip a status unilaterally — is in [`AGENTS.md`](../../../../AGENTS.md). ## An ADR is a decision record, not a specification @@ -32,7 +32,7 @@ need editing. ## File conventions -* One file per decision, under `maintainers/adr/`, named +* One file per decision, under `doc/handwritten/for-maintainers/adr/`, named `NNNN-short-title.md` — a four-digit sequence number and a lowercase, kebab-case title: `0001-lock-the-analyzer-roslyn-floor.md`. * ADRs are written in **English** — the canonical version — with a French diff --git a/maintainers/adr/template.md b/doc/handwritten/for-maintainers/adr/template.md similarity index 97% rename from maintainers/adr/template.md rename to doc/handwritten/for-maintainers/adr/template.md index d5593b1..404468e 100644 --- a/maintainers/adr/template.md +++ b/doc/handwritten/for-maintainers/adr/template.md @@ -6,7 +6,7 @@ specification: it lives in the code and the reference docs (e.g. the workflow reference), which this ADR links to. Test: if the implementation changed but the decision stood, this ADR should not need editing. - See maintainers/adr/README.md. --> + See doc/handwritten/for-maintainers/adr/README.md. --> **Status:** Proposed **Date:** YYYY-MM-DD diff --git a/maintainers/workflows/README.fr.md b/doc/handwritten/for-maintainers/workflows/README.fr.md similarity index 97% rename from maintainers/workflows/README.fr.md rename to doc/handwritten/for-maintainers/workflows/README.fr.md index 9f752cb..b98192e 100644 --- a/maintainers/workflows/README.fr.md +++ b/doc/handwritten/for-maintainers/workflows/README.fr.md @@ -10,7 +10,7 @@ ## De quoi il s'agit -Chaque workflow sous [`.github/workflows/`](../../.github/workflows/) porte une +Chaque workflow sous [`.github/workflows/`](../../../../.github/workflows/) porte une intention qu'il est facile de casser en « faisant le ménage » : une permission volontairement étroite, un ordre d'étapes qui protège d'une panne précise, une version gelée pour une raison produit. Les fichiers de workflow eux-mêmes @@ -101,5 +101,5 @@ documentées une seule fois ici plutôt que répétées sur chaque page. - [ADR 0001 — Verrouiller le floor Roslyn de l'analyzer](../adr/0001-lock-the-analyzer-roslyn-floor.md) — pourquoi la version de Roslyn de l'analyzer est gelée, ce que le workflow `analyzers` fait respecter. *(Rédigé en anglais.)* -- [`CONTRIBUTING.fr.md`](../../doc/CONTRIBUTING.fr.md) — les conventions de commit et de PR +- [`CONTRIBUTING.fr.md`](../../for-users/CONTRIBUTING.fr.md) — les conventions de commit et de PR que le workflow `commit-lint` vérifie. diff --git a/maintainers/workflows/README.md b/doc/handwritten/for-maintainers/workflows/README.md similarity index 96% rename from maintainers/workflows/README.md rename to doc/handwritten/for-maintainers/workflows/README.md index 13955a7..b6c8c57 100644 --- a/maintainers/workflows/README.md +++ b/doc/handwritten/for-maintainers/workflows/README.md @@ -10,7 +10,7 @@ ## What this is -Each workflow under [`.github/workflows/`](../../.github/workflows/) carries a +Each workflow under [`.github/workflows/`](../../../../.github/workflows/) carries a fair amount of intent that is easy to break by "cleaning it up": a permission that is narrow on purpose, a step ordering that guards a specific failure, a version that is frozen for a product reason. The workflow files themselves hold @@ -97,5 +97,5 @@ here instead of being repeated on every page. - [ADR 0001 — Lock the analyzer Roslyn floor](../adr/0001-lock-the-analyzer-roslyn-floor.md) — why the analyzer's Roslyn version is frozen, which the `analyzers` workflow enforces. -- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — the commit and PR conventions the +- [`CONTRIBUTING.md`](../../../../CONTRIBUTING.md) — the commit and PR conventions the `commit-lint` workflow checks. diff --git a/maintainers/workflows/adr-check.en.md b/doc/handwritten/for-maintainers/workflows/adr-check.en.md similarity index 90% rename from maintainers/workflows/adr-check.en.md rename to doc/handwritten/for-maintainers/workflows/adr-check.en.md index 78896a4..0d835ba 100644 --- a/maintainers/workflows/adr-check.en.md +++ b/doc/handwritten/for-maintainers/workflows/adr-check.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/adr-check.yml`](../../.github/workflows/adr-check.yml) +**Workflow file:** [`.github/workflows/adr-check.yml`](../../../../.github/workflows/adr-check.yml) ## What it is for @@ -13,7 +13,7 @@ an architectural decision the project records as an [ADR](../adr/README.md). It is the **manual fallback** for a contributor **without Claude Code** — whose coding session performs the same check automatically (see -[`AGENTS.md`](../../AGENTS.md) → "Architecture decisions"). Same three outcomes, +[`AGENTS.md`](../../../../AGENTS.md) → "Architecture decisions"). Same three outcomes, run on demand from the Actions tab instead of inside a session. It is **advisory**: it **never blocks** anything and **never writes an ADR**. It @@ -48,11 +48,11 @@ One job, `adr-check`: 3. Resolve `base` into the branch's **fork point** (`git merge-base`), so the diff is exactly what the branch introduces. 4. **Collect context** with - [`tools/adr-check/collect-context.sh`](../../tools/adr-check/collect-context.sh): + [`tools/adr-check/collect-context.sh`](../../../../tools/adr-check/collect-context.sh): the changed-file list and the unified diff (from `git`, byte-capped) plus the current ADR base (index and each ADR, byte-capped), as one delimited bundle. 5. **Ask the model** under - [`.github/adr-check-prompt.md`](../../.github/adr-check-prompt.md), which defines + [`.github/adr-check-prompt.md`](../../../../.github/adr-check-prompt.md), which defines the three outcomes, biases hard toward silence, and requires a single JSON verdict `{ analysis, needs_report, outcomes, report }`. 6. **Write the verdict to the run summary** (`$GITHUB_STEP_SUMMARY`) — the primary @@ -61,7 +61,7 @@ One job, `adr-check`: 7. **Mirror it to the pull request, if one is open** for the branch: when `needs_report` is true the report is posted (or refreshed) as the single comment found by the hidden `<!-- adr-check -->` marker, via - [`tools/adr-check/upsert-comment.sh`](../../tools/adr-check/upsert-comment.sh); + [`tools/adr-check/upsert-comment.sh`](../../../../tools/adr-check/upsert-comment.sh); when false, any stale comment is removed. With no open pull request, the summary is the only output. @@ -104,7 +104,7 @@ is open — it writes nothing to the repository. ## Related -- [`AGENTS.md`](../../AGENTS.md) — the code-authoring agent's own ADR check, run +- [`AGENTS.md`](../../../../AGENTS.md) — the code-authoring agent's own ADR check, run automatically in a Claude Code session; this workflow is its manual counterpart for contributors without Claude Code. - [ADR reference](../adr/README.md) — the format, conventions, and "when is an ADR diff --git a/maintainers/workflows/adr-check.fr.md b/doc/handwritten/for-maintainers/workflows/adr-check.fr.md similarity index 92% rename from maintainers/workflows/adr-check.fr.md rename to doc/handwritten/for-maintainers/workflows/adr-check.fr.md index 3e0d9f6..b1688f2 100644 --- a/maintainers/workflows/adr-check.fr.md +++ b/doc/handwritten/for-maintainers/workflows/adr-check.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/adr-check.yml`](../../.github/workflows/adr-check.yml) +**Fichier du workflow :** [`.github/workflows/adr-check.yml`](../../../../.github/workflows/adr-check.yml) ## À quoi il sert @@ -13,7 +13,7 @@ une décision d'architecture que le projet consigne en [ADR](../adr/README.md). C'est le **repli manuel** pour un contributeur **sans Claude Code** — dont la session de codage effectue le même contrôle automatiquement (voir -[`AGENTS.md`](../../AGENTS.md) → « Architecture decisions »). Les trois mêmes issues, +[`AGENTS.md`](../../../../AGENTS.md) → « Architecture decisions »). Les trois mêmes issues, lancées à la demande depuis l'onglet Actions au lieu de l'être dans une session. Il est **consultatif** : il **ne bloque jamais** rien et **n'écrit jamais d'ADR**. @@ -49,12 +49,12 @@ Un seul job, `adr-check` : 3. Résout `base` en le **point de divergence** de la branche (`git merge-base`), pour que le diff soit exactement ce que la branche introduit. 4. **Collecte le contexte** avec - [`tools/adr-check/collect-context.sh`](../../tools/adr-check/collect-context.sh) : + [`tools/adr-check/collect-context.sh`](../../../../tools/adr-check/collect-context.sh) : la liste des fichiers modifiés et le diff unifié (via `git`, plafonné en octets) plus la base d'ADR courante (index et chaque ADR, plafonnée en octets), en un seul paquet délimité. 5. **Interroge le modèle** sous - [`.github/adr-check-prompt.md`](../../.github/adr-check-prompt.md), qui définit les + [`.github/adr-check-prompt.md`](../../../../.github/adr-check-prompt.md), qui définit les trois issues, pousse fortement vers le silence, et exige un unique verdict JSON `{ analysis, needs_report, outcomes, report }`. 6. **Écrit le verdict dans le résumé de run** (`$GITHUB_STEP_SUMMARY`) — la sortie @@ -63,7 +63,7 @@ Un seul job, `adr-check` : 7. **Le reflète sur la pull request, s'il y en a une d'ouverte** pour la branche : quand `needs_report` est vrai, le rapport est posté (ou rafraîchi) comme l'unique commentaire repéré par le marqueur caché `<!-- adr-check -->`, via - [`tools/adr-check/upsert-comment.sh`](../../tools/adr-check/upsert-comment.sh) ; + [`tools/adr-check/upsert-comment.sh`](../../../../tools/adr-check/upsert-comment.sh) ; quand c'est faux, le commentaire qui traîne est retiré. Sans pull request ouverte, le résumé est la seule sortie. @@ -108,7 +108,7 @@ pull request est ouverte — il n'écrit rien dans le dépôt. ## En rapport -- [`AGENTS.md`](../../AGENTS.md) — le contrôle ADR propre à l'agent qui écrit le code, +- [`AGENTS.md`](../../../../AGENTS.md) — le contrôle ADR propre à l'agent qui écrit le code, lancé automatiquement dans une session Claude Code ; ce workflow en est le pendant manuel pour les contributeurs sans Claude Code. - [Référence des ADR](../adr/README.md) — le format, les conventions et la note diff --git a/maintainers/workflows/analyzers.en.md b/doc/handwritten/for-maintainers/workflows/analyzers.en.md similarity index 98% rename from maintainers/workflows/analyzers.en.md rename to doc/handwritten/for-maintainers/workflows/analyzers.en.md index 7fbfdef..79c5d63 100644 --- a/maintainers/workflows/analyzers.en.md +++ b/doc/handwritten/for-maintainers/workflows/analyzers.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/analyzers.yml`](../../.github/workflows/analyzers.yml) +**Workflow file:** [`.github/workflows/analyzers.yml`](../../../../.github/workflows/analyzers.yml) ## What it is for diff --git a/maintainers/workflows/analyzers.fr.md b/doc/handwritten/for-maintainers/workflows/analyzers.fr.md similarity index 99% rename from maintainers/workflows/analyzers.fr.md rename to doc/handwritten/for-maintainers/workflows/analyzers.fr.md index e7c1bb6..e31138e 100644 --- a/maintainers/workflows/analyzers.fr.md +++ b/doc/handwritten/for-maintainers/workflows/analyzers.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/analyzers.yml`](../../.github/workflows/analyzers.yml) +**Fichier du workflow :** [`.github/workflows/analyzers.yml`](../../../../.github/workflows/analyzers.yml) ## À quoi il sert diff --git a/maintainers/workflows/changelog.en.md b/doc/handwritten/for-maintainers/workflows/changelog.en.md similarity index 90% rename from maintainers/workflows/changelog.en.md rename to doc/handwritten/for-maintainers/workflows/changelog.en.md index 7259cde..b9c8999 100644 --- a/maintainers/workflows/changelog.en.md +++ b/doc/handwritten/for-maintainers/workflows/changelog.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/changelog.yml`](../../.github/workflows/changelog.yml) +**Workflow file:** [`.github/workflows/changelog.yml`](../../../../.github/workflows/changelog.yml) ## What it is for @@ -15,7 +15,7 @@ with the result. It never publishes anything and never writes to a released section — it produces a **draft for a human to review and merge**. It fills a gap the [`release`](release.en.md) path leaves open. -[`tools/packaging/release-notes.sh`](../../tools/packaging/release-notes.sh) +[`tools/packaging/release-notes.sh`](../../../../tools/packaging/release-notes.sh) already generates the GitHub Release body, but those notes are **commit-oriented and raw** ("`- feat(core): … (abc1234)`"), scoped to one train. This workflow produces the complementary artifact: a **narrative, user-facing changelog** in @@ -27,8 +27,8 @@ The two trains version independently and keep **separate** changelog files: | Train | Scopes | Changelog file | | --- | --- | --- | -| `lib` | `core`, `analyzers`, `testing` | [`CHANGELOG.md`](../../CHANGELOG.md) | -| `cli` | `cli`, `gendoc` | [`FirstClassErrors.Cli/CHANGELOG.md`](../../FirstClassErrors.Cli/CHANGELOG.md) | +| `lib` | `core`, `analyzers`, `testing` | [`CHANGELOG.md`](../../../../CHANGELOG.md) | +| `cli` | `cli`, `gendoc` | [`FirstClassErrors.Cli/CHANGELOG.md`](../../../../FirstClassErrors.Cli/CHANGELOG.md) | ## When it runs @@ -50,7 +50,7 @@ One job, `draft-changelog`: with **`fetch-depth: 0`** — the train's previous tag (and its commit timestamp, the lower bound of the pull-request range) must resolve. 2. **Collect** the train's pull requests with - [`tools/changelog/collect-prs.sh`](../../tools/changelog/collect-prs.sh): + [`tools/changelog/collect-prs.sh`](../../../../tools/changelog/collect-prs.sh): `gh pr list` gathers the candidates merged into `main` after the tag's commit time, then each candidate is kept only if one of **its commits' Conventional Commit scopes** falls in the train's set. This is the **same partition @@ -59,10 +59,10 @@ One job, `draft-changelog`: `chore:` / `docs:`) belong to neither train and are dropped from both. 3. **Draft** the entry: the merged PRs (number, title, body, labels, author) are sent to the Anthropic API under - [`.github/changelog-prompt.md`](../../.github/changelog-prompt.md), which + [`.github/changelog-prompt.md`](../../../../.github/changelog-prompt.md), which instructs the model to group the changes and **invent nothing**. 4. **Merge** the drafted block into the train's changelog file with - [`tools/changelog/merge-unreleased.sh`](../../tools/changelog/merge-unreleased.sh), + [`tools/changelog/merge-unreleased.sh`](../../../../tools/changelog/merge-unreleased.sh), which **replaces** the `[Unreleased]` section in place. 5. **Open** (or refresh) a pull request from `github-actions/changelog-<component>-draft` via `gh`, for review. The refresh @@ -86,7 +86,7 @@ to a pull request from a fork — the key is never exposed to fork PRs. ## Handle with care -- **The train partition lives in one place: [`tools/trains.sh`](../../tools/trains.sh).** +- **The train partition lives in one place: [`tools/trains.sh`](../../../../tools/trains.sh).** `collect-prs.sh`, `release-notes.sh` and this workflow all *source* it, so the changelog and the GitHub Release notes can never disagree on which scopes belong to which train (`lib` → core/analyzers/testing, `cli` → cli/gendoc). Add a train, @@ -141,8 +141,8 @@ to a pull request from a fork — the key is never exposed to fork PRs. - [`release`](release.en.md) — the tag-driven publish, whose `release-notes.sh` produces the raw, commit-oriented GitHub Release body this changelog complements. -- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — the Conventional Commit **scopes** +- [`CONTRIBUTING.md`](../../../../CONTRIBUTING.md) — the Conventional Commit **scopes** the train partition is built on. -- The two changelog files: [`CHANGELOG.md`](../../CHANGELOG.md) (lib) and - [`FirstClassErrors.Cli/CHANGELOG.md`](../../FirstClassErrors.Cli/CHANGELOG.md) +- The two changelog files: [`CHANGELOG.md`](../../../../CHANGELOG.md) (lib) and + [`FirstClassErrors.Cli/CHANGELOG.md`](../../../../FirstClassErrors.Cli/CHANGELOG.md) (cli). diff --git a/maintainers/workflows/changelog.fr.md b/doc/handwritten/for-maintainers/workflows/changelog.fr.md similarity index 92% rename from maintainers/workflows/changelog.fr.md rename to doc/handwritten/for-maintainers/workflows/changelog.fr.md index 74656c0..589835d 100644 --- a/maintainers/workflows/changelog.fr.md +++ b/doc/handwritten/for-maintainers/workflows/changelog.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/changelog.yml`](../../.github/workflows/changelog.yml) +**Fichier du workflow :** [`.github/workflows/changelog.yml`](../../../../.github/workflows/changelog.yml) ## À quoi il sert @@ -15,7 +15,7 @@ pull request avec le résultat. Il ne publie jamais rien et n'écrit jamais dans section déjà publiée — il produit un **brouillon qu'un humain relit et merge**. Il comble un manque que le chemin [`release`](release.fr.md) laisse ouvert. -[`tools/packaging/release-notes.sh`](../../tools/packaging/release-notes.sh) +[`tools/packaging/release-notes.sh`](../../../../tools/packaging/release-notes.sh) génère déjà le corps de la GitHub Release, mais ces notes sont **orientées commits et brutes** (« `- feat(core): … (abc1234)` »), cantonnées à un train. Ce workflow produit l'artefact complémentaire : un **changelog narratif, orienté utilisateur**, @@ -28,8 +28,8 @@ changelog **distincts** : | Train | Scopes | Fichier de changelog | | --- | --- | --- | -| `lib` | `core`, `analyzers`, `testing` | [`CHANGELOG.md`](../../CHANGELOG.md) | -| `cli` | `cli`, `gendoc` | [`FirstClassErrors.Cli/CHANGELOG.md`](../../FirstClassErrors.Cli/CHANGELOG.md) | +| `lib` | `core`, `analyzers`, `testing` | [`CHANGELOG.md`](../../../../CHANGELOG.md) | +| `cli` | `cli`, `gendoc` | [`FirstClassErrors.Cli/CHANGELOG.md`](../../../../FirstClassErrors.Cli/CHANGELOG.md) | ## Quand il s'exécute @@ -54,7 +54,7 @@ Un seul job, `draft-changelog` : (et l'horodatage de son commit, la borne basse de la plage de pull requests) doit se résoudre. 2. **Collecter** les pull requests du train avec - [`tools/changelog/collect-prs.sh`](../../tools/changelog/collect-prs.sh) : + [`tools/changelog/collect-prs.sh`](../../../../tools/changelog/collect-prs.sh) : `gh pr list` rassemble les candidates mergées dans `main` après l'heure du commit taggé, puis chaque candidate n'est conservée que si l'un des **scopes Conventional Commit de ses commits** tombe dans l'ensemble du train. C'est la @@ -64,10 +64,10 @@ Un seul job, `draft-changelog` : écartées des deux. 3. **Rédiger** l'entrée : les PR mergées (numéro, titre, corps, labels, auteur) sont envoyées à l'API Anthropic sous - [`.github/changelog-prompt.md`](../../.github/changelog-prompt.md), qui demande + [`.github/changelog-prompt.md`](../../../../.github/changelog-prompt.md), qui demande au modèle de grouper les changements et de **n'inventer rien**. 4. **Fusionner** le bloc rédigé dans le fichier de changelog du train avec - [`tools/changelog/merge-unreleased.sh`](../../tools/changelog/merge-unreleased.sh), + [`tools/changelog/merge-unreleased.sh`](../../../../tools/changelog/merge-unreleased.sh), qui **remplace** la section `[Unreleased]` sur place. 5. **Ouvrir** (ou rafraîchir) une pull request depuis `github-actions/changelog-<component>-draft` via `gh`, pour relecture. Le @@ -93,7 +93,7 @@ exposée aux PR de forks. ## À manipuler avec précaution -- **La partition par train vit à un seul endroit : [`tools/trains.sh`](../../tools/trains.sh).** +- **La partition par train vit à un seul endroit : [`tools/trains.sh`](../../../../tools/trains.sh).** `collect-prs.sh`, `release-notes.sh` et ce workflow le *sourcent* tous, donc le changelog et les notes de release GitHub ne peuvent jamais diverger sur quels scopes appartiennent à quel train (`lib` → core/analyzers/testing, `cli` → @@ -154,8 +154,8 @@ exposée aux PR de forks. - [`release`](release.fr.md) — la publication pilotée par tag, dont le `release-notes.sh` produit le corps de GitHub Release brut et orienté commits que ce changelog complète. -- [`CONTRIBUTING.fr.md`](../../doc/CONTRIBUTING.fr.md) — les **scopes** Conventional +- [`CONTRIBUTING.fr.md`](../../for-users/CONTRIBUTING.fr.md) — les **scopes** Conventional Commit sur lesquels repose la partition par train. -- Les deux fichiers de changelog : [`CHANGELOG.md`](../../CHANGELOG.md) (lib) et - [`FirstClassErrors.Cli/CHANGELOG.md`](../../FirstClassErrors.Cli/CHANGELOG.md) +- Les deux fichiers de changelog : [`CHANGELOG.md`](../../../../CHANGELOG.md) (lib) et + [`FirstClassErrors.Cli/CHANGELOG.md`](../../../../FirstClassErrors.Cli/CHANGELOG.md) (cli). diff --git a/maintainers/workflows/ci.en.md b/doc/handwritten/for-maintainers/workflows/ci.en.md similarity index 93% rename from maintainers/workflows/ci.en.md rename to doc/handwritten/for-maintainers/workflows/ci.en.md index 4e0db25..ca3c7bf 100644 --- a/maintainers/workflows/ci.en.md +++ b/doc/handwritten/for-maintainers/workflows/ci.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) +**Workflow file:** [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml) ## What it is for @@ -40,7 +40,7 @@ On a `[ubuntu-latest, windows-latest]` matrix: 1. Checkout, then set up the .NET SDK. 2. `dotnet restore` → `dotnet build -c Release` → `dotnet test -c Release`. 3. Tests collect OpenCover coverage via `coverlet.collector`, configured by - [`coverage.runsettings`](../../coverage.runsettings), into + [`coverage.runsettings`](../../../../coverage.runsettings), into `artifacts/coverage/<guid>/coverage.opencover.xml`. 4. The coverage report is uploaded as a per-OS artifact. @@ -76,7 +76,7 @@ secrets and needs no write scope. would let a broken coverage setup pass unnoticed. It should fail. - **This is the enforcement point for the warning ratchet.** The `TreatWarningsAsErrors` / `MSBuildTreatWarningsAsErrors` promotion (see - [`Directory.Build.props`](../../Directory.Build.props)) is scoped to CI and is + [`Directory.Build.props`](../../../../Directory.Build.props)) is scoped to CI and is *enforced here*, on both OS legs. The `sonar` workflow deliberately disables it for its own analysis build — so `ci`, not `sonar`, is the gate that must stay green on warnings. @@ -99,7 +99,7 @@ secrets and needs no write scope. - [`sonar`](sonar.en.md) reuses the same `coverage.runsettings` so its coverage report matches this one. - [`analyzers`](analyzers.en.md) covers the analyzer dogfood that `ci` does not. -- [`canary.yml`](../../.github/workflows/canary.yml) *(no reference page yet)* +- [`canary.yml`](../../../../.github/workflows/canary.yml) *(no reference page yet)* runs the same net8 tooling on the next .NET **preview**, weekly, to catch a roll-forward regression onto a not-yet-released major before it ships — the one surface the `floor` job cannot cover (see ADR 0002). diff --git a/maintainers/workflows/ci.fr.md b/doc/handwritten/for-maintainers/workflows/ci.fr.md similarity index 94% rename from maintainers/workflows/ci.fr.md rename to doc/handwritten/for-maintainers/workflows/ci.fr.md index 42765ef..c9fd159 100644 --- a/maintainers/workflows/ci.fr.md +++ b/doc/handwritten/for-maintainers/workflows/ci.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) +**Fichier du workflow :** [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml) ## À quoi il sert @@ -42,7 +42,7 @@ Sur une matrice `[ubuntu-latest, windows-latest]` : 1. Checkout, puis installation du SDK .NET. 2. `dotnet restore` → `dotnet build -c Release` → `dotnet test -c Release`. 3. Les tests collectent la couverture OpenCover via `coverlet.collector`, - configuré par [`coverage.runsettings`](../../coverage.runsettings), dans + configuré par [`coverage.runsettings`](../../../../coverage.runsettings), dans `artifacts/coverage/<guid>/coverage.opencover.xml`. 4. Le rapport de couverture est uploadé en artefact, un par OS. @@ -79,7 +79,7 @@ stocke aucun secret et n'a besoin d'aucun périmètre en écriture. Ça doit échouer. - **C'est ici que le cliquet de warnings est imposé.** La promotion `TreatWarningsAsErrors` / `MSBuildTreatWarningsAsErrors` (voir - [`Directory.Build.props`](../../Directory.Build.props)) est cantonnée à la CI et + [`Directory.Build.props`](../../../../Directory.Build.props)) est cantonnée à la CI et *imposée ici*, sur les deux branches OS. Le workflow `sonar` la désactive volontairement pour son propre build d'analyse — c'est donc `ci`, et non `sonar`, le barrage qui doit rester vert sur les warnings. @@ -104,7 +104,7 @@ stocke aucun secret et n'a besoin d'aucun périmètre en écriture. rapport de couverture corresponde à celui-ci. - [`analyzers`](analyzers.fr.md) couvre le dogfood des analyzers que `ci` ne fait pas. -- [`canary.yml`](../../.github/workflows/canary.yml) *(pas encore de page de +- [`canary.yml`](../../../../.github/workflows/canary.yml) *(pas encore de page de référence)* fait tourner le même outillage net8 sur la **preview** .NET suivante, chaque semaine, pour attraper une régression de roll-forward vers un major pas encore publié avant qu'il ne sorte — la seule surface que le job diff --git a/maintainers/workflows/codeql.en.md b/doc/handwritten/for-maintainers/workflows/codeql.en.md similarity index 96% rename from maintainers/workflows/codeql.en.md rename to doc/handwritten/for-maintainers/workflows/codeql.en.md index cf9ae08..60ca5a1 100644 --- a/maintainers/workflows/codeql.en.md +++ b/doc/handwritten/for-maintainers/workflows/codeql.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/codeql.yml`](../../.github/workflows/codeql.yml) +**Workflow file:** [`.github/workflows/codeql.yml`](../../../../.github/workflows/codeql.yml) ## What it is for diff --git a/maintainers/workflows/codeql.fr.md b/doc/handwritten/for-maintainers/workflows/codeql.fr.md similarity index 98% rename from maintainers/workflows/codeql.fr.md rename to doc/handwritten/for-maintainers/workflows/codeql.fr.md index 287f17c..125c102 100644 --- a/maintainers/workflows/codeql.fr.md +++ b/doc/handwritten/for-maintainers/workflows/codeql.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/codeql.yml`](../../.github/workflows/codeql.yml) +**Fichier du workflow :** [`.github/workflows/codeql.yml`](../../../../.github/workflows/codeql.yml) ## À quoi il sert diff --git a/maintainers/workflows/commit-lint.en.md b/doc/handwritten/for-maintainers/workflows/commit-lint.en.md similarity index 87% rename from maintainers/workflows/commit-lint.en.md rename to doc/handwritten/for-maintainers/workflows/commit-lint.en.md index 8c8e42b..5d4194a 100644 --- a/maintainers/workflows/commit-lint.en.md +++ b/doc/handwritten/for-maintainers/workflows/commit-lint.en.md @@ -5,18 +5,18 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/commit-lint.yml`](../../.github/workflows/commit-lint.yml) +**Workflow file:** [`.github/workflows/commit-lint.yml`](../../../../.github/workflows/commit-lint.yml) ## What it is for It enforces the repository's commit-message convention (Conventional Commits, as -specified in [`CONTRIBUTING.md`](../../CONTRIBUTING.md)) on **every non-merge +specified in [`CONTRIBUTING.md`](../../../../CONTRIBUTING.md)) on **every non-merge commit of a pull request**. It is the server-side backstop for the local `commit-msg` hook: a contributor who bypasses the hook with `git commit --no-verify` is still caught here. Both the hook and this workflow call the **same script**, -[`tools/commit-lint/lint-commit-message.sh`](../../tools/commit-lint/lint-commit-message.sh), +[`tools/commit-lint/lint-commit-message.sh`](../../../../tools/commit-lint/lint-commit-message.sh), so there is exactly one definition of "a valid commit message" and CI can never drift from the local check. @@ -55,6 +55,6 @@ One job, `Conventional commits`: ## Related -- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — the commit and PR conventions this +- [`CONTRIBUTING.md`](../../../../CONTRIBUTING.md) — the commit and PR conventions this workflow enforces. Enable the local hook once per clone with `git config core.hooksPath .githooks`. diff --git a/maintainers/workflows/commit-lint.fr.md b/doc/handwritten/for-maintainers/workflows/commit-lint.fr.md similarity index 87% rename from maintainers/workflows/commit-lint.fr.md rename to doc/handwritten/for-maintainers/workflows/commit-lint.fr.md index 82c343a..2ed2371 100644 --- a/maintainers/workflows/commit-lint.fr.md +++ b/doc/handwritten/for-maintainers/workflows/commit-lint.fr.md @@ -5,18 +5,18 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/commit-lint.yml`](../../.github/workflows/commit-lint.yml) +**Fichier du workflow :** [`.github/workflows/commit-lint.yml`](../../../../.github/workflows/commit-lint.yml) ## À quoi il sert Il impose la convention de message de commit du dépôt (Conventional Commits, -telle que spécifiée dans [`CONTRIBUTING.fr.md`](../../doc/CONTRIBUTING.fr.md)) sur **chaque +telle que spécifiée dans [`CONTRIBUTING.fr.md`](../../for-users/CONTRIBUTING.fr.md)) sur **chaque commit non-merge d'une pull request**. C'est le filet de sécurité côté serveur du hook local `commit-msg` : un contributeur qui contourne le hook avec `git commit --no-verify` est quand même rattrapé ici. Le hook et ce workflow appellent le **même script**, -[`tools/commit-lint/lint-commit-message.sh`](../../tools/commit-lint/lint-commit-message.sh), +[`tools/commit-lint/lint-commit-message.sh`](../../../../tools/commit-lint/lint-commit-message.sh), donc il existe exactement une définition de « message de commit valide » et la CI ne peut jamais diverger du contrôle local. @@ -56,6 +56,6 @@ Un seul job, `Conventional commits` : ## En rapport -- [`CONTRIBUTING.fr.md`](../../doc/CONTRIBUTING.fr.md) — les conventions de commit et de PR +- [`CONTRIBUTING.fr.md`](../../for-users/CONTRIBUTING.fr.md) — les conventions de commit et de PR que ce workflow impose. Activez le hook local une fois par clone avec `git config core.hooksPath .githooks`. diff --git a/maintainers/workflows/dependabot-automerge.en.md b/doc/handwritten/for-maintainers/workflows/dependabot-automerge.en.md similarity index 91% rename from maintainers/workflows/dependabot-automerge.en.md rename to doc/handwritten/for-maintainers/workflows/dependabot-automerge.en.md index 05796be..4427248 100644 --- a/maintainers/workflows/dependabot-automerge.en.md +++ b/doc/handwritten/for-maintainers/workflows/dependabot-automerge.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/dependabot-automerge.yml`](../../.github/workflows/dependabot-automerge.yml) +**Workflow file:** [`.github/workflows/dependabot-automerge.yml`](../../../../.github/workflows/dependabot-automerge.yml) ## What it is for @@ -16,7 +16,7 @@ is the low-friction lane of the dependency-update policy: routine bumps do not need a human, risky ones do. The Dependabot configuration itself (which ecosystems, schedule, ignored -packages) lives in [`.github/dependabot.yml`](../../.github/dependabot.yml), not +packages) lives in [`.github/dependabot.yml`](../../../../.github/dependabot.yml), not here. ## When it runs @@ -54,7 +54,7 @@ Workflow default `contents: read`; the job widens to `contents: write` and ## Related -- [`.github/dependabot.yml`](../../.github/dependabot.yml) — what Dependabot +- [`.github/dependabot.yml`](../../../../.github/dependabot.yml) — what Dependabot updates and what it ignores (e.g. the frozen `Microsoft.CodeAnalysis.*`; see [`analyzers`](analyzers.en.md)). - [`dependency-review`](dependency-review.en.md) — the PR-time vulnerability gate diff --git a/maintainers/workflows/dependabot-automerge.fr.md b/doc/handwritten/for-maintainers/workflows/dependabot-automerge.fr.md similarity index 92% rename from maintainers/workflows/dependabot-automerge.fr.md rename to doc/handwritten/for-maintainers/workflows/dependabot-automerge.fr.md index abdd0d0..15d41d0 100644 --- a/maintainers/workflows/dependabot-automerge.fr.md +++ b/doc/handwritten/for-maintainers/workflows/dependabot-automerge.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/dependabot-automerge.yml`](../../.github/workflows/dependabot-automerge.yml) +**Fichier du workflow :** [`.github/workflows/dependabot-automerge.yml`](../../../../.github/workflows/dependabot-automerge.yml) ## À quoi il sert @@ -17,7 +17,7 @@ voie à faible friction de la politique de mise à jour des dépendances : les montées de routine n'ont pas besoin d'un humain, les risquées si. La configuration de Dependabot elle-même (quels écosystèmes, planning, packages -ignorés) vit dans [`.github/dependabot.yml`](../../.github/dependabot.yml), pas +ignorés) vit dans [`.github/dependabot.yml`](../../../../.github/dependabot.yml), pas ici. ## Quand il s'exécute @@ -58,7 +58,7 @@ la PR. ## En rapport -- [`.github/dependabot.yml`](../../.github/dependabot.yml) — ce que Dependabot met +- [`.github/dependabot.yml`](../../../../.github/dependabot.yml) — ce que Dependabot met à jour et ce qu'il ignore (p. ex. les `Microsoft.CodeAnalysis.*` gelés ; voir [`analyzers`](analyzers.fr.md)). - [`dependency-review`](dependency-review.fr.md) — le barrage de vulnérabilité au diff --git a/maintainers/workflows/dependency-review.en.md b/doc/handwritten/for-maintainers/workflows/dependency-review.en.md similarity index 94% rename from maintainers/workflows/dependency-review.en.md rename to doc/handwritten/for-maintainers/workflows/dependency-review.en.md index 461b061..969764f 100644 --- a/maintainers/workflows/dependency-review.en.md +++ b/doc/handwritten/for-maintainers/workflows/dependency-review.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/dependency-review.yml`](../../.github/workflows/dependency-review.yml) +**Workflow file:** [`.github/workflows/dependency-review.yml`](../../../../.github/workflows/dependency-review.yml) ## What it is for @@ -42,7 +42,7 @@ check is the signal. Advanced Security.) - **It only sees changes the PR makes.** A CVE published overnight against an *existing* dependency does not fail this check — that stays a warning through - the NuGet audit (see [`Directory.Build.props`](../../Directory.Build.props)). + the NuGet audit (see [`Directory.Build.props`](../../../../Directory.Build.props)). This workflow blocks only at the point of introduction, on purpose. - **`fail-on-severity: moderate` is the tuning knob.** Lower it to `low` to be stricter, raise it to `high` to be laxer. Because it only inspects the PR's own diff --git a/maintainers/workflows/dependency-review.fr.md b/doc/handwritten/for-maintainers/workflows/dependency-review.fr.md similarity index 94% rename from maintainers/workflows/dependency-review.fr.md rename to doc/handwritten/for-maintainers/workflows/dependency-review.fr.md index 03c9225..57a2966 100644 --- a/maintainers/workflows/dependency-review.fr.md +++ b/doc/handwritten/for-maintainers/workflows/dependency-review.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/dependency-review.yml`](../../.github/workflows/dependency-review.yml) +**Fichier du workflow :** [`.github/workflows/dependency-review.yml`](../../../../.github/workflows/dependency-review.yml) ## À quoi il sert @@ -44,7 +44,7 @@ le check en échec est le signal. - **Il ne voit que les changements apportés par la PR.** Une CVE publiée pendant la nuit contre une dépendance *existante* ne fait pas échouer ce check — cela reste un warning via l'audit NuGet (voir - [`Directory.Build.props`](../../Directory.Build.props)). Ce workflow ne bloque + [`Directory.Build.props`](../../../../Directory.Build.props)). Ce workflow ne bloque qu'au point d'introduction, à dessein. - **`fail-on-severity: moderate` est le bouton de réglage.** Abaissez-le à `low` pour être plus strict, montez-le à `high` pour être plus laxiste. Comme il diff --git a/maintainers/workflows/release-dryrun.en.md b/doc/handwritten/for-maintainers/workflows/release-dryrun.en.md similarity index 98% rename from maintainers/workflows/release-dryrun.en.md rename to doc/handwritten/for-maintainers/workflows/release-dryrun.en.md index a7ca3a2..8639e73 100644 --- a/maintainers/workflows/release-dryrun.en.md +++ b/doc/handwritten/for-maintainers/workflows/release-dryrun.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/release-dryrun.yml`](../../.github/workflows/release-dryrun.yml) +**Workflow file:** [`.github/workflows/release-dryrun.yml`](../../../../.github/workflows/release-dryrun.yml) ## What it is for diff --git a/maintainers/workflows/release-dryrun.fr.md b/doc/handwritten/for-maintainers/workflows/release-dryrun.fr.md similarity index 98% rename from maintainers/workflows/release-dryrun.fr.md rename to doc/handwritten/for-maintainers/workflows/release-dryrun.fr.md index aed1d5c..a5610fe 100644 --- a/maintainers/workflows/release-dryrun.fr.md +++ b/doc/handwritten/for-maintainers/workflows/release-dryrun.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/release-dryrun.yml`](../../.github/workflows/release-dryrun.yml) +**Fichier du workflow :** [`.github/workflows/release-dryrun.yml`](../../../../.github/workflows/release-dryrun.yml) ## À quoi il sert diff --git a/maintainers/workflows/release.en.md b/doc/handwritten/for-maintainers/workflows/release.en.md similarity index 98% rename from maintainers/workflows/release.en.md rename to doc/handwritten/for-maintainers/workflows/release.en.md index a0d1198..07a1e23 100644 --- a/maintainers/workflows/release.en.md +++ b/doc/handwritten/for-maintainers/workflows/release.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/release.yml`](../../.github/workflows/release.yml) +**Workflow file:** [`.github/workflows/release.yml`](../../../../.github/workflows/release.yml) ## What it is for diff --git a/maintainers/workflows/release.fr.md b/doc/handwritten/for-maintainers/workflows/release.fr.md similarity index 99% rename from maintainers/workflows/release.fr.md rename to doc/handwritten/for-maintainers/workflows/release.fr.md index 64eac84..68d3ef6 100644 --- a/maintainers/workflows/release.fr.md +++ b/doc/handwritten/for-maintainers/workflows/release.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/release.yml`](../../.github/workflows/release.yml) +**Fichier du workflow :** [`.github/workflows/release.yml`](../../../../.github/workflows/release.yml) ## À quoi il sert diff --git a/maintainers/workflows/scorecard.en.md b/doc/handwritten/for-maintainers/workflows/scorecard.en.md similarity index 97% rename from maintainers/workflows/scorecard.en.md rename to doc/handwritten/for-maintainers/workflows/scorecard.en.md index bb32f21..aa2ed48 100644 --- a/maintainers/workflows/scorecard.en.md +++ b/doc/handwritten/for-maintainers/workflows/scorecard.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/scorecard.yml`](../../.github/workflows/scorecard.yml) +**Workflow file:** [`.github/workflows/scorecard.yml`](../../../../.github/workflows/scorecard.yml) ## What it is for diff --git a/maintainers/workflows/scorecard.fr.md b/doc/handwritten/for-maintainers/workflows/scorecard.fr.md similarity index 99% rename from maintainers/workflows/scorecard.fr.md rename to doc/handwritten/for-maintainers/workflows/scorecard.fr.md index 3db7222..aa1bdde 100644 --- a/maintainers/workflows/scorecard.fr.md +++ b/doc/handwritten/for-maintainers/workflows/scorecard.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/scorecard.yml`](../../.github/workflows/scorecard.yml) +**Fichier du workflow :** [`.github/workflows/scorecard.yml`](../../../../.github/workflows/scorecard.yml) ## À quoi il sert diff --git a/maintainers/workflows/sonar.en.md b/doc/handwritten/for-maintainers/workflows/sonar.en.md similarity index 96% rename from maintainers/workflows/sonar.en.md rename to doc/handwritten/for-maintainers/workflows/sonar.en.md index 9ace285..99c26d3 100644 --- a/maintainers/workflows/sonar.en.md +++ b/doc/handwritten/for-maintainers/workflows/sonar.en.md @@ -5,7 +5,7 @@ > Maintainer documentation — part of the [workflow reference](README.md). > Not part of the user documentation under `doc/`. -**Workflow file:** [`.github/workflows/sonar.yml`](../../.github/workflows/sonar.yml) +**Workflow file:** [`.github/workflows/sonar.yml`](../../../../.github/workflows/sonar.yml) ## What it is for diff --git a/maintainers/workflows/sonar.fr.md b/doc/handwritten/for-maintainers/workflows/sonar.fr.md similarity index 98% rename from maintainers/workflows/sonar.fr.md rename to doc/handwritten/for-maintainers/workflows/sonar.fr.md index c7727de..8c59a95 100644 --- a/maintainers/workflows/sonar.fr.md +++ b/doc/handwritten/for-maintainers/workflows/sonar.fr.md @@ -5,7 +5,7 @@ > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md). > Ne fait pas partie de la documentation utilisateur sous `doc/`. -**Fichier du workflow :** [`.github/workflows/sonar.yml`](../../.github/workflows/sonar.yml) +**Fichier du workflow :** [`.github/workflows/sonar.yml`](../../../../.github/workflows/sonar.yml) ## À quoi il sert diff --git a/doc/ArbitraryTestValues.en.md b/doc/handwritten/for-users/ArbitraryTestValues.en.md similarity index 97% rename from doc/ArbitraryTestValues.en.md rename to doc/handwritten/for-users/ArbitraryTestValues.en.md index bd1e201..a85db62 100644 --- a/doc/ArbitraryTestValues.en.md +++ b/doc/handwritten/for-users/ArbitraryTestValues.en.md @@ -113,7 +113,7 @@ Before reaching for an arbitrary value, verify that: --- <div align="center"> -<a href="DeterministicTesting.en.md">← Deterministic Error Tests</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="OperationalIntegration.en.md">Generating and Publishing the Catalog →</a> +<a href="DeterministicTesting.en.md">← Deterministic Error Tests</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="OperationalIntegration.en.md">Generating and Publishing the Catalog →</a> </div> --- diff --git a/doc/ArbitraryTestValues.fr.md b/doc/handwritten/for-users/ArbitraryTestValues.fr.md similarity index 100% rename from doc/ArbitraryTestValues.fr.md rename to doc/handwritten/for-users/ArbitraryTestValues.fr.md diff --git a/doc/ArchitectureOfTheDocumentationPipeline.en.md b/doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md similarity index 97% rename from doc/ArchitectureOfTheDocumentationPipeline.en.md rename to doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md index 2c589ca..7581fb0 100644 --- a/doc/ArchitectureOfTheDocumentationPipeline.en.md +++ b/doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md @@ -184,7 +184,7 @@ The code remains the source of truth; the pipeline makes that knowledge portable --- <div align="center"> -<a href="CatalogVersioning.en.md">← Catalog Versioning</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="DocumentationExtractionReference.en.md">Extraction and Project Discovery Reference →</a> +<a href="CatalogVersioning.en.md">← Catalog Versioning</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="DocumentationExtractionReference.en.md">Extraction and Project Discovery Reference →</a> </div> --- \ No newline at end of file diff --git a/doc/ArchitectureOfTheDocumentationPipeline.fr.md b/doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.fr.md similarity index 100% rename from doc/ArchitectureOfTheDocumentationPipeline.fr.md rename to doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.fr.md diff --git a/doc/BestPractices.en.md b/doc/handwritten/for-users/BestPractices.en.md similarity index 97% rename from doc/BestPractices.en.md rename to doc/handwritten/for-users/BestPractices.en.md index 22952eb..183092f 100644 --- a/doc/BestPractices.en.md +++ b/doc/handwritten/for-users/BestPractices.en.md @@ -111,7 +111,7 @@ Before merging an error-related change, verify that: --- <div align="center"> -<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="Testing.en.md">Testing Guide →</a> +<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="Testing.en.md">Testing Guide →</a> </div> --- \ No newline at end of file diff --git a/doc/BestPractices.fr.md b/doc/handwritten/for-users/BestPractices.fr.md similarity index 100% rename from doc/BestPractices.fr.md rename to doc/handwritten/for-users/BestPractices.fr.md diff --git a/doc/CONTRIBUTING.fr.md b/doc/handwritten/for-users/CONTRIBUTING.fr.md similarity index 99% rename from doc/CONTRIBUTING.fr.md rename to doc/handwritten/for-users/CONTRIBUTING.fr.md index 6f83a4d..2d9b3ac 100644 --- a/doc/CONTRIBUTING.fr.md +++ b/doc/handwritten/for-users/CONTRIBUTING.fr.md @@ -1,7 +1,7 @@ # Contribuer à FirstClassErrors 🌍 **Langues:** -🇬🇧 [English](../CONTRIBUTING.md) | 🇫🇷 Français (ce fichier) +🇬🇧 [English](../../../CONTRIBUTING.md) | 🇫🇷 Français (ce fichier) FirstClassErrors considère les erreurs comme des concepts de premier ordre, documentés et diagnostiquables. L’historique du dépôt doit être aussi lisible que @@ -15,7 +15,7 @@ commits sont écrits ici. * Tester : `dotnet test FirstClassErrors.sln` * Tests des analyzers, lorsque vous touchez aux analyzers : `dotnet test FirstClassErrors.Analyzers.UnitTests` -Voir [`CLAUDE.md`](../CLAUDE.md) pour l’organisation du projet et les lignes +Voir [`CLAUDE.md`](../../../CLAUDE.md) pour l’organisation du projet et les lignes directrices plus larges concernant les changements. ## Activer le hook de message de commit @@ -472,7 +472,7 @@ Classés comme le sont les règles : type, scope, description, corps, breaking, ### Adoption Ce guide est la règle pour les commits de ce dépôt. S’en écarter requiert une justification — -un ADR sous `maintainers/adr/`, ou une mise à jour de ce guide. +un ADR sous `doc/handwritten/for-maintainers/adr/`, ou une mise à jour de ce guide. Il s’applique à partir de son adoption, à chaque commit créé après. L’historique antérieur n’est pas réécrit. diff --git a/doc/CatalogVersioning.en.md b/doc/handwritten/for-users/CatalogVersioning.en.md similarity index 97% rename from doc/CatalogVersioning.en.md rename to doc/handwritten/for-users/CatalogVersioning.en.md index 26e1ffe..a39320a 100644 --- a/doc/CatalogVersioning.en.md +++ b/doc/handwritten/for-users/CatalogVersioning.en.md @@ -163,7 +163,7 @@ A rename remains breaking because consumers know the old code. When the title su --- <div align="center"> -<a href="OperationalIntegration.en.md">← CI/CD and Operational Integration</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioningReference.en.md">Command reference →</a> +<a href="OperationalIntegration.en.md">← CI/CD and Operational Integration</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioningReference.en.md">Command reference →</a> </div> --- \ No newline at end of file diff --git a/doc/CatalogVersioning.fr.md b/doc/handwritten/for-users/CatalogVersioning.fr.md similarity index 100% rename from doc/CatalogVersioning.fr.md rename to doc/handwritten/for-users/CatalogVersioning.fr.md diff --git a/doc/CatalogVersioningCI.en.md b/doc/handwritten/for-users/CatalogVersioningCI.en.md similarity index 97% rename from doc/CatalogVersioningCI.en.md rename to doc/handwritten/for-users/CatalogVersioningCI.en.md index 0440dde..3c1ac3b 100644 --- a/doc/CatalogVersioningCI.en.md +++ b/doc/handwritten/for-users/CatalogVersioningCI.en.md @@ -214,7 +214,7 @@ This form can produce release notes for the error contract or compare the previo --- <div align="center"> -<a href="CatalogVersioningReference.en.md">← Command reference</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="ArchitectureOfTheDocumentationPipeline.en.md">Architecture of the Documentation Pipeline →</a> +<a href="CatalogVersioningReference.en.md">← Command reference</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="ArchitectureOfTheDocumentationPipeline.en.md">Architecture of the Documentation Pipeline →</a> </div> --- diff --git a/doc/CatalogVersioningCI.fr.md b/doc/handwritten/for-users/CatalogVersioningCI.fr.md similarity index 100% rename from doc/CatalogVersioningCI.fr.md rename to doc/handwritten/for-users/CatalogVersioningCI.fr.md diff --git a/doc/CatalogVersioningReference.en.md b/doc/handwritten/for-users/CatalogVersioningReference.en.md similarity index 97% rename from doc/CatalogVersioningReference.en.md rename to doc/handwritten/for-users/CatalogVersioningReference.en.md index 13fe18c..3d2a62f 100644 --- a/doc/CatalogVersioningReference.en.md +++ b/doc/handwritten/for-users/CatalogVersioningReference.en.md @@ -147,7 +147,7 @@ The `catalog update` and `catalog diff` commands accept, among others: --- <div align="center"> -<a href="CatalogVersioning.en.md">← Catalog versioning guide</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioningCI.en.md">CI/CD integration →</a> +<a href="CatalogVersioning.en.md">← Catalog versioning guide</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioningCI.en.md">CI/CD integration →</a> </div> --- \ No newline at end of file diff --git a/doc/CatalogVersioningReference.fr.md b/doc/handwritten/for-users/CatalogVersioningReference.fr.md similarity index 100% rename from doc/CatalogVersioningReference.fr.md rename to doc/handwritten/for-users/CatalogVersioningReference.fr.md diff --git a/doc/ComparisonWithOtherLibraries.en.md b/doc/handwritten/for-users/ComparisonWithOtherLibraries.en.md similarity index 100% rename from doc/ComparisonWithOtherLibraries.en.md rename to doc/handwritten/for-users/ComparisonWithOtherLibraries.en.md diff --git a/doc/ComparisonWithOtherLibraries.fr.md b/doc/handwritten/for-users/ComparisonWithOtherLibraries.fr.md similarity index 100% rename from doc/ComparisonWithOtherLibraries.fr.md rename to doc/handwritten/for-users/ComparisonWithOtherLibraries.fr.md diff --git a/doc/CoreConcepts.en.md b/doc/handwritten/for-users/CoreConcepts.en.md similarity index 96% rename from doc/CoreConcepts.en.md rename to doc/handwritten/for-users/CoreConcepts.en.md index 92b3300..c5d18ea 100644 --- a/doc/CoreConcepts.en.md +++ b/doc/handwritten/for-users/CoreConcepts.en.md @@ -151,7 +151,7 @@ Their interaction direction, transience, and composition rules are explained sep --- <div align="center"> -<a href="WhenNotToUseFirstClassErrors.en.md">← When Not to Use FirstClassErrors</a> · <a href="../README.md#-documentation">↑ Table of contents</a> · <a href="ErrorTaxonomy.en.md">Error Taxonomy and Composition →</a> +<a href="WhenNotToUseFirstClassErrors.en.md">← When Not to Use FirstClassErrors</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="ErrorTaxonomy.en.md">Error Taxonomy and Composition →</a> </div> --- diff --git a/doc/CoreConcepts.fr.md b/doc/handwritten/for-users/CoreConcepts.fr.md similarity index 100% rename from doc/CoreConcepts.fr.md rename to doc/handwritten/for-users/CoreConcepts.fr.md diff --git a/doc/DesignPrinciples.en.md b/doc/handwritten/for-users/DesignPrinciples.en.md similarity index 96% rename from doc/DesignPrinciples.en.md rename to doc/handwritten/for-users/DesignPrinciples.en.md index 31b5ef4..7e20d58 100644 --- a/doc/DesignPrinciples.en.md +++ b/doc/handwritten/for-users/DesignPrinciples.en.md @@ -93,7 +93,7 @@ The factory defines one meaningful situation. The `Error` preserves that meaning --- <div align="center"> -<a href="GettingStarted.en.md">← Getting Started</a> · <a href="../README.md#-documentation">↑ Table of contents</a> · <a href="WhenNotToUseFirstClassErrors.en.md">When Not to Use FirstClassErrors →</a> +<a href="GettingStarted.en.md">← Getting Started</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="WhenNotToUseFirstClassErrors.en.md">When Not to Use FirstClassErrors →</a> </div> --- diff --git a/doc/DesignPrinciples.fr.md b/doc/handwritten/for-users/DesignPrinciples.fr.md similarity index 100% rename from doc/DesignPrinciples.fr.md rename to doc/handwritten/for-users/DesignPrinciples.fr.md diff --git a/doc/DeterministicTesting.en.md b/doc/handwritten/for-users/DeterministicTesting.en.md similarity index 98% rename from doc/DeterministicTesting.en.md rename to doc/handwritten/for-users/DeterministicTesting.en.md index d1af274..5fd4a17 100644 --- a/doc/DeterministicTesting.en.md +++ b/doc/handwritten/for-users/DeterministicTesting.en.md @@ -203,7 +203,7 @@ Before approving a deterministic error test, verify that: --- <div align="center"> -<a href="Testing.en.md">← Testing Outcomes and Errors</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="ArbitraryTestValues.en.md">Arbitrary Test Values →</a> +<a href="Testing.en.md">← Testing Outcomes and Errors</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="ArbitraryTestValues.en.md">Arbitrary Test Values →</a> </div> --- \ No newline at end of file diff --git a/doc/DeterministicTesting.fr.md b/doc/handwritten/for-users/DeterministicTesting.fr.md similarity index 100% rename from doc/DeterministicTesting.fr.md rename to doc/handwritten/for-users/DeterministicTesting.fr.md diff --git a/doc/DocumentationExtractionReference.en.md b/doc/handwritten/for-users/DocumentationExtractionReference.en.md similarity index 98% rename from doc/DocumentationExtractionReference.en.md rename to doc/handwritten/for-users/DocumentationExtractionReference.en.md index 5cc1452..34c01f4 100644 --- a/doc/DocumentationExtractionReference.en.md +++ b/doc/handwritten/for-users/DocumentationExtractionReference.en.md @@ -280,7 +280,7 @@ When expected errors are missing, walk the pipeline in order — each step depen --- <div align="center"> -<a href="ArchitectureOfTheDocumentationPipeline.en.md">← Architecture of the Documentation Pipeline</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingACustomRenderer.en.md">Writing a custom renderer →</a> +<a href="ArchitectureOfTheDocumentationPipeline.en.md">← Architecture of the Documentation Pipeline</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingACustomRenderer.en.md">Writing a custom renderer →</a> </div> --- \ No newline at end of file diff --git a/doc/DocumentationExtractionReference.fr.md b/doc/handwritten/for-users/DocumentationExtractionReference.fr.md similarity index 100% rename from doc/DocumentationExtractionReference.fr.md rename to doc/handwritten/for-users/DocumentationExtractionReference.fr.md diff --git a/doc/DocumentationMap.en.md b/doc/handwritten/for-users/DocumentationMap.en.md similarity index 98% rename from doc/DocumentationMap.en.md rename to doc/handwritten/for-users/DocumentationMap.en.md index 1df9e4a..838c8b7 100644 --- a/doc/DocumentationMap.en.md +++ b/doc/handwritten/for-users/DocumentationMap.en.md @@ -110,7 +110,7 @@ This keeps local conventions short while allowing the library documentation to e --- <div align="center"> -<a href="../README.md">← Project README</a> · <a href="GettingStarted.en.md">Start with Getting Started →</a> +<a href="../../../README.md">← Project README</a> · <a href="GettingStarted.en.md">Start with Getting Started →</a> </div> --- \ No newline at end of file diff --git a/doc/DocumentationMap.fr.md b/doc/handwritten/for-users/DocumentationMap.fr.md similarity index 100% rename from doc/DocumentationMap.fr.md rename to doc/handwritten/for-users/DocumentationMap.fr.md diff --git a/doc/ErrorContext.en.md b/doc/handwritten/for-users/ErrorContext.en.md similarity index 98% rename from doc/ErrorContext.en.md rename to doc/handwritten/for-users/ErrorContext.en.md index 4ec741e..e253d09 100644 --- a/doc/ErrorContext.en.md +++ b/doc/handwritten/for-users/ErrorContext.en.md @@ -173,7 +173,7 @@ If the answer is yes to all six, it is a strong context candidate. --- <div align="center"> -<a href="CoreConcepts.en.md">← Core Concepts</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingErrorsGuide.en.md">Writing Errors Guide →</a> +<a href="CoreConcepts.en.md">← Core Concepts</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingErrorsGuide.en.md">Writing Errors Guide →</a> </div> --- \ No newline at end of file diff --git a/doc/ErrorContext.fr.md b/doc/handwritten/for-users/ErrorContext.fr.md similarity index 100% rename from doc/ErrorContext.fr.md rename to doc/handwritten/for-users/ErrorContext.fr.md diff --git a/doc/ErrorTaxonomy.en.md b/doc/handwritten/for-users/ErrorTaxonomy.en.md similarity index 98% rename from doc/ErrorTaxonomy.en.md rename to doc/handwritten/for-users/ErrorTaxonomy.en.md index 6cc3a66..8ac451f 100644 --- a/doc/ErrorTaxonomy.en.md +++ b/doc/handwritten/for-users/ErrorTaxonomy.en.md @@ -159,7 +159,7 @@ Do not choose a type from the current class or folder. Choose it from the meanin --- <div align="center"> -<a href="CoreConcepts.en.md">← Core Concepts</a> · <a href="../README.md#-documentation">↑ Table of contents</a> · <a href="ErrorContext.en.md">Error Context Guide →</a> +<a href="CoreConcepts.en.md">← Core Concepts</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="ErrorContext.en.md">Error Context Guide →</a> </div> --- diff --git a/doc/ErrorTaxonomy.fr.md b/doc/handwritten/for-users/ErrorTaxonomy.fr.md similarity index 100% rename from doc/ErrorTaxonomy.fr.md rename to doc/handwritten/for-users/ErrorTaxonomy.fr.md diff --git a/doc/FAQ.en.md b/doc/handwritten/for-users/FAQ.en.md similarity index 99% rename from doc/FAQ.en.md rename to doc/handwritten/for-users/FAQ.en.md index 7dd76f5..e0af048 100644 --- a/doc/FAQ.en.md +++ b/doc/handwritten/for-users/FAQ.en.md @@ -130,7 +130,7 @@ See [Error Taxonomy and Composition](ErrorTaxonomy.en.md). --- <div align="center"> -<a href="Internationalization.en.md">← Internationalization</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> +<a href="Internationalization.en.md">← Internationalization</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> </div> --- diff --git a/doc/FAQ.fr.md b/doc/handwritten/for-users/FAQ.fr.md similarity index 100% rename from doc/FAQ.fr.md rename to doc/handwritten/for-users/FAQ.fr.md diff --git a/doc/GettingStarted.en.md b/doc/handwritten/for-users/GettingStarted.en.md similarity index 98% rename from doc/GettingStarted.en.md rename to doc/handwritten/for-users/GettingStarted.en.md index d065def..02c5467 100644 --- a/doc/GettingStarted.en.md +++ b/doc/handwritten/for-users/GettingStarted.en.md @@ -178,7 +178,7 @@ Commit or publish this generated catalog according to your delivery workflow. Fo --- <div align="center"> -<a href="../README.md#-documentation">↑ Table of contents</a> · <a href="DesignPrinciples.en.md">Design Principles →</a> +<a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="DesignPrinciples.en.md">Design Principles →</a> </div> --- diff --git a/doc/GettingStarted.fr.md b/doc/handwritten/for-users/GettingStarted.fr.md similarity index 100% rename from doc/GettingStarted.fr.md rename to doc/handwritten/for-users/GettingStarted.fr.md diff --git a/doc/Internationalisation.fr.md b/doc/handwritten/for-users/Internationalisation.fr.md similarity index 100% rename from doc/Internationalisation.fr.md rename to doc/handwritten/for-users/Internationalisation.fr.md diff --git a/doc/Internationalization.en.md b/doc/handwritten/for-users/Internationalization.en.md similarity index 98% rename from doc/Internationalization.en.md rename to doc/handwritten/for-users/Internationalization.en.md index 9d07799..2739818 100644 --- a/doc/Internationalization.en.md +++ b/doc/handwritten/for-users/Internationalization.en.md @@ -250,7 +250,7 @@ Before publishing localized catalogs, verify that: --- <div align="center"> -<a href="WritingACustomRenderer.en.md">← Writing a custom renderer</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="FAQ.en.md">FAQ →</a> +<a href="WritingACustomRenderer.en.md">← Writing a custom renderer</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="FAQ.en.md">FAQ →</a> </div> --- \ No newline at end of file diff --git a/doc/LoggingIntegration.en.md b/doc/handwritten/for-users/LoggingIntegration.en.md similarity index 98% rename from doc/LoggingIntegration.en.md rename to doc/handwritten/for-users/LoggingIntegration.en.md index e546a4b..9dbee02 100644 --- a/doc/LoggingIntegration.en.md +++ b/doc/handwritten/for-users/LoggingIntegration.en.md @@ -267,7 +267,7 @@ Before approving a logging integration, verify that: --- <div align="center"> -<a href="OperationalIntegration.en.md">← Generating and Publishing the Catalog</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioning.en.md">Catalog Versioning →</a> +<a href="OperationalIntegration.en.md">← Generating and Publishing the Catalog</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioning.en.md">Catalog Versioning →</a> </div> --- \ No newline at end of file diff --git a/doc/LoggingIntegration.fr.md b/doc/handwritten/for-users/LoggingIntegration.fr.md similarity index 100% rename from doc/LoggingIntegration.fr.md rename to doc/handwritten/for-users/LoggingIntegration.fr.md diff --git a/doc/OperationalIntegration.en.md b/doc/handwritten/for-users/OperationalIntegration.en.md similarity index 98% rename from doc/OperationalIntegration.en.md rename to doc/handwritten/for-users/OperationalIntegration.en.md index d1cd799..12807d6 100644 --- a/doc/OperationalIntegration.en.md +++ b/doc/handwritten/for-users/OperationalIntegration.en.md @@ -237,7 +237,7 @@ Before approving a catalog-delivery pipeline, verify that: --- <div align="center"> -<a href="ArbitraryTestValues.en.md">← Arbitrary Test Values</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="LoggingIntegration.en.md">Integrate FirstClassErrors with Structured Logging →</a> +<a href="ArbitraryTestValues.en.md">← Arbitrary Test Values</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="LoggingIntegration.en.md">Integrate FirstClassErrors with Structured Logging →</a> </div> --- \ No newline at end of file diff --git a/doc/OperationalIntegration.fr.md b/doc/handwritten/for-users/OperationalIntegration.fr.md similarity index 100% rename from doc/OperationalIntegration.fr.md rename to doc/handwritten/for-users/OperationalIntegration.fr.md diff --git a/doc/OutcomeGuide.en.md b/doc/handwritten/for-users/OutcomeGuide.en.md similarity index 98% rename from doc/OutcomeGuide.en.md rename to doc/handwritten/for-users/OutcomeGuide.en.md index 881a1d6..4e6823a 100644 --- a/doc/OutcomeGuide.en.md +++ b/doc/handwritten/for-users/OutcomeGuide.en.md @@ -241,7 +241,7 @@ Before approving an `Outcome` flow, verify that: --- <div align="center"> -<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="BestPractices.en.md">Best Practices →</a> +<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="BestPractices.en.md">Best Practices →</a> </div> --- \ No newline at end of file diff --git a/doc/OutcomeGuide.fr.md b/doc/handwritten/for-users/OutcomeGuide.fr.md similarity index 100% rename from doc/OutcomeGuide.fr.md rename to doc/handwritten/for-users/OutcomeGuide.fr.md diff --git a/doc/README.fr.md b/doc/handwritten/for-users/README.fr.md similarity index 97% rename from doc/README.fr.md rename to doc/handwritten/for-users/README.fr.md index 351e5b4..1f016da 100644 --- a/doc/README.fr.md +++ b/doc/handwritten/for-users/README.fr.md @@ -1,7 +1,7 @@ # FirstClassErrors 🌍 **Langues :** -🇬🇧 [English](../README.md) | 🇫🇷 Français (ce fichier) +🇬🇧 [English](../../../README.md) | 🇫🇷 Français (ce fichier) | | | | :-- | :-- | @@ -9,7 +9,7 @@ | **Qualité** | [![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=reefact_first-class-errors&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=reefact_first-class-errors) [![Couverture](https://sonarcloud.io/api/project_badges/measure?project=reefact_first-class-errors&metric=coverage)](https://sonarcloud.io/summary/new_code?id=reefact_first-class-errors) | | **Sécurité** | [![codeql](https://github.com/Reefact/first-class-errors/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/Reefact/first-class-errors/actions/workflows/codeql.yml) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13567/badge)](https://www.bestpractices.dev/projects/13567) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Reefact/first-class-errors/badge)](https://securityscorecards.dev/viewer/?uri=github.com/Reefact/first-class-errors) | | **Package** | [![NuGet](https://img.shields.io/nuget/vpre/FirstClassErrors?logo=nuget)](https://www.nuget.org/packages/FirstClassErrors) ![.NET Standard 2.0](https://img.shields.io/badge/.NET%20Standard-2.0-512BD4) | -| **Projet** | [![License](https://img.shields.io/github/license/Reefact/first-class-errors)](../LICENSE) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fe5196?logo=conventionalcommits&logoColor=white)](https://www.conventionalcommits.org) | +| **Projet** | [![License](https://img.shields.io/github/license/Reefact/first-class-errors)](../../../LICENSE) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fe5196?logo=conventionalcommits&logoColor=white)](https://www.conventionalcommits.org) | --- diff --git a/doc/RequestBinder.en.md b/doc/handwritten/for-users/RequestBinder.en.md similarity index 99% rename from doc/RequestBinder.en.md rename to doc/handwritten/for-users/RequestBinder.en.md index 70a40ef..9323ecd 100644 --- a/doc/RequestBinder.en.md +++ b/doc/handwritten/for-users/RequestBinder.en.md @@ -242,7 +242,7 @@ not an argument-binding failure), so it is not re-wrapped in the binder envelope A consumer of `Create` therefore sees either the binder's envelope (a field was missing or malformed) or the factory's own error (all fields were fine, but the combination was rejected). The decision behind these two names is recorded in -[ADR-0007](../maintainers/adr/0007-name-the-binder-terminals-new-and-create.md). +[ADR-0007](../for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.md). ## Collect-all, not fail-fast @@ -489,7 +489,7 @@ Before approving a binding, verify that: --- <div align="center"> -<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../README.md#-documentation">↑ Table of contents</a> · <a href="Testing.en.md">Testing →</a> +<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="Testing.en.md">Testing →</a> </div> --- diff --git a/doc/RequestBinder.fr.md b/doc/handwritten/for-users/RequestBinder.fr.md similarity index 99% rename from doc/RequestBinder.fr.md rename to doc/handwritten/for-users/RequestBinder.fr.md index 346d8bf..2daf292 100644 --- a/doc/RequestBinder.fr.md +++ b/doc/handwritten/for-users/RequestBinder.fr.md @@ -249,7 +249,7 @@ ré-emballée dans l’enveloppe du binder. Un consommateur de `Create` voit don l’enveloppe du binder (un champ manquant ou malformé), soit l’erreur propre de la fabrique (tous les champs allaient bien, mais la combinaison a été rejetée). La décision derrière ces deux noms est consignée dans -[ADR-0007](../maintainers/adr/0007-name-the-binder-terminals-new-and-create.md). +[ADR-0007](../for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.md). ## Tout collecter, pas au premier échec diff --git a/doc/SECURITY.fr.md b/doc/handwritten/for-users/SECURITY.fr.md similarity index 98% rename from doc/SECURITY.fr.md rename to doc/handwritten/for-users/SECURITY.fr.md index b86eae0..6ca3e9b 100644 --- a/doc/SECURITY.fr.md +++ b/doc/handwritten/for-users/SECURITY.fr.md @@ -1,7 +1,7 @@ # Politique de sécurité 🌍 **Langues:** -🇬🇧 [English](../SECURITY.md) | 🇫🇷 Français (ce fichier) +🇬🇧 [English](../../../SECURITY.md) | 🇫🇷 Français (ce fichier) ## Versions prises en charge diff --git a/doc/Testing.en.md b/doc/handwritten/for-users/Testing.en.md similarity index 97% rename from doc/Testing.en.md rename to doc/handwritten/for-users/Testing.en.md index f6b4b18..fdcd5f8 100644 --- a/doc/Testing.en.md +++ b/doc/handwritten/for-users/Testing.en.md @@ -166,7 +166,7 @@ Before approving an error test, verify that: --- <div align="center"> -<a href="BestPractices.en.md">← Best Practices</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="DeterministicTesting.en.md">Deterministic Error Tests →</a> +<a href="BestPractices.en.md">← Best Practices</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="DeterministicTesting.en.md">Deterministic Error Tests →</a> </div> --- \ No newline at end of file diff --git a/doc/Testing.fr.md b/doc/handwritten/for-users/Testing.fr.md similarity index 100% rename from doc/Testing.fr.md rename to doc/handwritten/for-users/Testing.fr.md diff --git a/doc/TheHtmlRenderer.en.md b/doc/handwritten/for-users/TheHtmlRenderer.en.md similarity index 100% rename from doc/TheHtmlRenderer.en.md rename to doc/handwritten/for-users/TheHtmlRenderer.en.md diff --git a/doc/TheHtmlRenderer.fr.md b/doc/handwritten/for-users/TheHtmlRenderer.fr.md similarity index 100% rename from doc/TheHtmlRenderer.fr.md rename to doc/handwritten/for-users/TheHtmlRenderer.fr.md diff --git a/doc/UsagePatterns.en.md b/doc/handwritten/for-users/UsagePatterns.en.md similarity index 98% rename from doc/UsagePatterns.en.md rename to doc/handwritten/for-users/UsagePatterns.en.md index 097efac..641d441 100644 --- a/doc/UsagePatterns.en.md +++ b/doc/handwritten/for-users/UsagePatterns.en.md @@ -199,7 +199,7 @@ Choose the contract from the first list, the error type from the second, and the --- <div align="center"> -<a href="WritingErrorsGuide.en.md">← Writing Errors Guide</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="OutcomeGuide.en.md">Composing with Outcome →</a> +<a href="WritingErrorsGuide.en.md">← Writing Errors Guide</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="OutcomeGuide.en.md">Composing with Outcome →</a> </div> --- \ No newline at end of file diff --git a/doc/UsagePatterns.fr.md b/doc/handwritten/for-users/UsagePatterns.fr.md similarity index 100% rename from doc/UsagePatterns.fr.md rename to doc/handwritten/for-users/UsagePatterns.fr.md diff --git a/doc/WhenNotToUseFirstClassErrors.en.md b/doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md similarity index 94% rename from doc/WhenNotToUseFirstClassErrors.en.md rename to doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md index f63a40c..d003dc6 100644 --- a/doc/WhenNotToUseFirstClassErrors.en.md +++ b/doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md @@ -73,7 +73,7 @@ The goal of this library is not to make every exception richer. It is to make me --- <div align="center"> -<a href="DesignPrinciples.en.md">← Design Principles</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="CoreConcepts.en.md">Core Concepts →</a> +<a href="DesignPrinciples.en.md">← Design Principles</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="CoreConcepts.en.md">Core Concepts →</a> </div> --- \ No newline at end of file diff --git a/doc/WhenNotToUseFirstClassErrors.fr.md b/doc/handwritten/for-users/WhenNotToUseFirstClassErrors.fr.md similarity index 100% rename from doc/WhenNotToUseFirstClassErrors.fr.md rename to doc/handwritten/for-users/WhenNotToUseFirstClassErrors.fr.md diff --git a/doc/WritingACustomRenderer.en.md b/doc/handwritten/for-users/WritingACustomRenderer.en.md similarity index 98% rename from doc/WritingACustomRenderer.en.md rename to doc/handwritten/for-users/WritingACustomRenderer.en.md index ef2557f..57e4dfc 100644 --- a/doc/WritingACustomRenderer.en.md +++ b/doc/handwritten/for-users/WritingACustomRenderer.en.md @@ -307,7 +307,7 @@ Before publishing a renderer, verify that: --- <div align="center"> -<a href="DocumentationExtractionReference.en.md">← Extraction and Project Discovery Reference</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="Internationalization.en.md">Internationalization →</a> +<a href="DocumentationExtractionReference.en.md">← Extraction and Project Discovery Reference</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="Internationalization.en.md">Internationalization →</a> </div> --- \ No newline at end of file diff --git a/doc/WritingACustomRenderer.fr.md b/doc/handwritten/for-users/WritingACustomRenderer.fr.md similarity index 100% rename from doc/WritingACustomRenderer.fr.md rename to doc/handwritten/for-users/WritingACustomRenderer.fr.md diff --git a/doc/WritingErrorMessages.en.md b/doc/handwritten/for-users/WritingErrorMessages.en.md similarity index 98% rename from doc/WritingErrorMessages.en.md rename to doc/handwritten/for-users/WritingErrorMessages.en.md index bafbb68..7a9758d 100644 --- a/doc/WritingErrorMessages.en.md +++ b/doc/handwritten/for-users/WritingErrorMessages.en.md @@ -212,7 +212,7 @@ For the stable title, description, rule, diagnostics, and examples, return to [W --- <div align="center"> -<a href="WritingErrorsGuide.en.md">← Writing Error Documentation</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="UsagePatterns.en.md">Usage Patterns →</a> +<a href="WritingErrorsGuide.en.md">← Writing Error Documentation</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="UsagePatterns.en.md">Usage Patterns →</a> </div> --- \ No newline at end of file diff --git a/doc/WritingErrorMessages.fr.md b/doc/handwritten/for-users/WritingErrorMessages.fr.md similarity index 100% rename from doc/WritingErrorMessages.fr.md rename to doc/handwritten/for-users/WritingErrorMessages.fr.md diff --git a/doc/WritingErrorsGuide.en.md b/doc/handwritten/for-users/WritingErrorsGuide.en.md similarity index 98% rename from doc/WritingErrorsGuide.en.md rename to doc/handwritten/for-users/WritingErrorsGuide.en.md index 58f2bf9..325059e 100644 --- a/doc/WritingErrorsGuide.en.md +++ b/doc/handwritten/for-users/WritingErrorsGuide.en.md @@ -218,7 +218,7 @@ For choosing public and internal runtime text, continue with [Writing Error Mess --- <div align="center"> -<a href="ErrorContext.en.md">← Error Context Guide</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingErrorMessages.en.md">Writing Error Messages →</a> +<a href="ErrorContext.en.md">← Error Context Guide</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingErrorMessages.en.md">Writing Error Messages →</a> </div> --- \ No newline at end of file diff --git a/doc/WritingErrorsGuide.fr.md b/doc/handwritten/for-users/WritingErrorsGuide.fr.md similarity index 100% rename from doc/WritingErrorsGuide.fr.md rename to doc/handwritten/for-users/WritingErrorsGuide.fr.md diff --git a/doc/analyzers/FCE001.en.md b/doc/handwritten/for-users/analyzers/FCE001.en.md similarity index 100% rename from doc/analyzers/FCE001.en.md rename to doc/handwritten/for-users/analyzers/FCE001.en.md diff --git a/doc/analyzers/FCE001.fr.md b/doc/handwritten/for-users/analyzers/FCE001.fr.md similarity index 100% rename from doc/analyzers/FCE001.fr.md rename to doc/handwritten/for-users/analyzers/FCE001.fr.md diff --git a/doc/analyzers/FCE002.en.md b/doc/handwritten/for-users/analyzers/FCE002.en.md similarity index 100% rename from doc/analyzers/FCE002.en.md rename to doc/handwritten/for-users/analyzers/FCE002.en.md diff --git a/doc/analyzers/FCE002.fr.md b/doc/handwritten/for-users/analyzers/FCE002.fr.md similarity index 100% rename from doc/analyzers/FCE002.fr.md rename to doc/handwritten/for-users/analyzers/FCE002.fr.md diff --git a/doc/analyzers/FCE003.en.md b/doc/handwritten/for-users/analyzers/FCE003.en.md similarity index 100% rename from doc/analyzers/FCE003.en.md rename to doc/handwritten/for-users/analyzers/FCE003.en.md diff --git a/doc/analyzers/FCE003.fr.md b/doc/handwritten/for-users/analyzers/FCE003.fr.md similarity index 100% rename from doc/analyzers/FCE003.fr.md rename to doc/handwritten/for-users/analyzers/FCE003.fr.md diff --git a/doc/analyzers/FCE004.en.md b/doc/handwritten/for-users/analyzers/FCE004.en.md similarity index 100% rename from doc/analyzers/FCE004.en.md rename to doc/handwritten/for-users/analyzers/FCE004.en.md diff --git a/doc/analyzers/FCE004.fr.md b/doc/handwritten/for-users/analyzers/FCE004.fr.md similarity index 100% rename from doc/analyzers/FCE004.fr.md rename to doc/handwritten/for-users/analyzers/FCE004.fr.md diff --git a/doc/analyzers/FCE005.en.md b/doc/handwritten/for-users/analyzers/FCE005.en.md similarity index 100% rename from doc/analyzers/FCE005.en.md rename to doc/handwritten/for-users/analyzers/FCE005.en.md diff --git a/doc/analyzers/FCE005.fr.md b/doc/handwritten/for-users/analyzers/FCE005.fr.md similarity index 100% rename from doc/analyzers/FCE005.fr.md rename to doc/handwritten/for-users/analyzers/FCE005.fr.md diff --git a/doc/analyzers/FCE006.en.md b/doc/handwritten/for-users/analyzers/FCE006.en.md similarity index 100% rename from doc/analyzers/FCE006.en.md rename to doc/handwritten/for-users/analyzers/FCE006.en.md diff --git a/doc/analyzers/FCE006.fr.md b/doc/handwritten/for-users/analyzers/FCE006.fr.md similarity index 100% rename from doc/analyzers/FCE006.fr.md rename to doc/handwritten/for-users/analyzers/FCE006.fr.md diff --git a/doc/analyzers/FCE007.en.md b/doc/handwritten/for-users/analyzers/FCE007.en.md similarity index 100% rename from doc/analyzers/FCE007.en.md rename to doc/handwritten/for-users/analyzers/FCE007.en.md diff --git a/doc/analyzers/FCE007.fr.md b/doc/handwritten/for-users/analyzers/FCE007.fr.md similarity index 100% rename from doc/analyzers/FCE007.fr.md rename to doc/handwritten/for-users/analyzers/FCE007.fr.md diff --git a/doc/analyzers/FCE008.en.md b/doc/handwritten/for-users/analyzers/FCE008.en.md similarity index 100% rename from doc/analyzers/FCE008.en.md rename to doc/handwritten/for-users/analyzers/FCE008.en.md diff --git a/doc/analyzers/FCE008.fr.md b/doc/handwritten/for-users/analyzers/FCE008.fr.md similarity index 100% rename from doc/analyzers/FCE008.fr.md rename to doc/handwritten/for-users/analyzers/FCE008.fr.md diff --git a/doc/analyzers/FCE009.en.md b/doc/handwritten/for-users/analyzers/FCE009.en.md similarity index 100% rename from doc/analyzers/FCE009.en.md rename to doc/handwritten/for-users/analyzers/FCE009.en.md diff --git a/doc/analyzers/FCE009.fr.md b/doc/handwritten/for-users/analyzers/FCE009.fr.md similarity index 100% rename from doc/analyzers/FCE009.fr.md rename to doc/handwritten/for-users/analyzers/FCE009.fr.md diff --git a/doc/analyzers/FCE010.en.md b/doc/handwritten/for-users/analyzers/FCE010.en.md similarity index 100% rename from doc/analyzers/FCE010.en.md rename to doc/handwritten/for-users/analyzers/FCE010.en.md diff --git a/doc/analyzers/FCE010.fr.md b/doc/handwritten/for-users/analyzers/FCE010.fr.md similarity index 100% rename from doc/analyzers/FCE010.fr.md rename to doc/handwritten/for-users/analyzers/FCE010.fr.md diff --git a/doc/analyzers/FCE011.en.md b/doc/handwritten/for-users/analyzers/FCE011.en.md similarity index 100% rename from doc/analyzers/FCE011.en.md rename to doc/handwritten/for-users/analyzers/FCE011.en.md diff --git a/doc/analyzers/FCE011.fr.md b/doc/handwritten/for-users/analyzers/FCE011.fr.md similarity index 100% rename from doc/analyzers/FCE011.fr.md rename to doc/handwritten/for-users/analyzers/FCE011.fr.md diff --git a/doc/analyzers/FCE012.en.md b/doc/handwritten/for-users/analyzers/FCE012.en.md similarity index 100% rename from doc/analyzers/FCE012.en.md rename to doc/handwritten/for-users/analyzers/FCE012.en.md diff --git a/doc/analyzers/FCE012.fr.md b/doc/handwritten/for-users/analyzers/FCE012.fr.md similarity index 100% rename from doc/analyzers/FCE012.fr.md rename to doc/handwritten/for-users/analyzers/FCE012.fr.md diff --git a/doc/analyzers/FCE013.en.md b/doc/handwritten/for-users/analyzers/FCE013.en.md similarity index 100% rename from doc/analyzers/FCE013.en.md rename to doc/handwritten/for-users/analyzers/FCE013.en.md diff --git a/doc/analyzers/FCE013.fr.md b/doc/handwritten/for-users/analyzers/FCE013.fr.md similarity index 100% rename from doc/analyzers/FCE013.fr.md rename to doc/handwritten/for-users/analyzers/FCE013.fr.md diff --git a/doc/analyzers/FCE014.en.md b/doc/handwritten/for-users/analyzers/FCE014.en.md similarity index 100% rename from doc/analyzers/FCE014.en.md rename to doc/handwritten/for-users/analyzers/FCE014.en.md diff --git a/doc/analyzers/FCE014.fr.md b/doc/handwritten/for-users/analyzers/FCE014.fr.md similarity index 100% rename from doc/analyzers/FCE014.fr.md rename to doc/handwritten/for-users/analyzers/FCE014.fr.md diff --git a/doc/analyzers/FCE015.en.md b/doc/handwritten/for-users/analyzers/FCE015.en.md similarity index 100% rename from doc/analyzers/FCE015.en.md rename to doc/handwritten/for-users/analyzers/FCE015.en.md diff --git a/doc/analyzers/FCE015.fr.md b/doc/handwritten/for-users/analyzers/FCE015.fr.md similarity index 100% rename from doc/analyzers/FCE015.fr.md rename to doc/handwritten/for-users/analyzers/FCE015.fr.md diff --git a/doc/analyzers/FCE016.en.md b/doc/handwritten/for-users/analyzers/FCE016.en.md similarity index 100% rename from doc/analyzers/FCE016.en.md rename to doc/handwritten/for-users/analyzers/FCE016.en.md diff --git a/doc/analyzers/FCE016.fr.md b/doc/handwritten/for-users/analyzers/FCE016.fr.md similarity index 100% rename from doc/analyzers/FCE016.fr.md rename to doc/handwritten/for-users/analyzers/FCE016.fr.md diff --git a/doc/analyzers/FCE017.en.md b/doc/handwritten/for-users/analyzers/FCE017.en.md similarity index 100% rename from doc/analyzers/FCE017.en.md rename to doc/handwritten/for-users/analyzers/FCE017.en.md diff --git a/doc/analyzers/FCE017.fr.md b/doc/handwritten/for-users/analyzers/FCE017.fr.md similarity index 100% rename from doc/analyzers/FCE017.fr.md rename to doc/handwritten/for-users/analyzers/FCE017.fr.md diff --git a/doc/analyzers/FCE018.en.md b/doc/handwritten/for-users/analyzers/FCE018.en.md similarity index 100% rename from doc/analyzers/FCE018.en.md rename to doc/handwritten/for-users/analyzers/FCE018.en.md diff --git a/doc/analyzers/FCE018.fr.md b/doc/handwritten/for-users/analyzers/FCE018.fr.md similarity index 100% rename from doc/analyzers/FCE018.fr.md rename to doc/handwritten/for-users/analyzers/FCE018.fr.md diff --git a/doc/analyzers/README.fr.md b/doc/handwritten/for-users/analyzers/README.fr.md similarity index 100% rename from doc/analyzers/README.fr.md rename to doc/handwritten/for-users/analyzers/README.fr.md diff --git a/doc/analyzers/README.md b/doc/handwritten/for-users/analyzers/README.md similarity index 100% rename from doc/analyzers/README.md rename to doc/handwritten/for-users/analyzers/README.md diff --git a/doc/images/first-class-errors.png b/doc/handwritten/for-users/images/first-class-errors.png similarity index 100% rename from doc/images/first-class-errors.png rename to doc/handwritten/for-users/images/first-class-errors.png diff --git a/tools/adr-check/collect-context.sh b/tools/adr-check/collect-context.sh index 4897cda..2c2dbab 100755 --- a/tools/adr-check/collect-context.sh +++ b/tools/adr-check/collect-context.sh @@ -20,7 +20,7 @@ base="${1:?usage: collect-context.sh <base-ref>}" DIFF_MAX_BYTES="${DIFF_MAX_BYTES:-200000}" ADR_MAX_BYTES="${ADR_MAX_BYTES:-120000}" -adr_dir="maintainers/adr" +adr_dir="doc/handwritten/for-maintainers/adr" # --- changed files (a strong, cheap signal on its own) ------------------------ # The set of touched paths already separates "only tests/docs" from "public API diff --git a/tools/packaging/pack.sh b/tools/packaging/pack.sh index ba7dc00..2f0c646 100755 --- a/tools/packaging/pack.sh +++ b/tools/packaging/pack.sh @@ -98,7 +98,7 @@ fi # content, so dropping the target (or PackAsTool ceasing to pack the publish output) would pass every local # check and only surface as "documentation worker could not be located" on a user's first `fce generate`. # A pack that stops bundling the worker must fail here, loudly, not in the field. This asserts presence; the -# closure is completeness-checked out of band by the tool-install smoke test in maintainers/ReleaseDryRun. +# closure is completeness-checked out of band by the tool-install smoke test in doc/handwritten/for-maintainers/ReleaseDryRun. if [ "$scope" = "cli" ]; then # The fce tool package carries the CLI's PackageId (FirstClassErrors.Cli), not the ToolCommandName (fce). for package in artifacts/FirstClassErrors.Cli.*.nupkg; do diff --git a/tools/trains.sh b/tools/trains.sh index 298da11..9902b8a 100644 --- a/tools/trains.sh +++ b/tools/trains.sh @@ -14,7 +14,7 @@ # ── Adding a train ──────────────────────────────────────────────────────────── # Add one row to trains_rows() below, then make the static edits GitHub forces # (tag trigger, choice options, commit-lint scopes, packaging). The full checklist -# is maintainers/AddingAReleaseTrain.en.md. +# is doc/handwritten/for-maintainers/AddingAReleaseTrain.en.md. # # Row format (pipe-separated, no spaces around the pipes except inside the label): # <id>|<tag-prefix>|<scopes csv>|<changelog file>|<package label> From 7cf826a47c4a440ec3c8ff605e42845cf29951e8 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Thu, 16 Jul 2026 17:11:37 +0000 Subject: [PATCH 2/2] docs: fix dead table-of-contents anchor in user guide footers Twenty English user-guide pages under doc/handwritten/for-users linked their footer "Table of contents" entry to README.md#-next-steps, an anchor that never existed: the root README's section is "## Documentation" (slug "-documentation"). Point them at that anchor, matching the five sibling English pages and every French page that already use it. This pre-existing broken anchor was surfaced while reorganizing the documentation tree; the change is limited to the dead fragment. Refs: #164 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YCDL8WVukKYb2mVUnsyPKZ --- doc/handwritten/for-users/ArbitraryTestValues.en.md | 2 +- .../for-users/ArchitectureOfTheDocumentationPipeline.en.md | 2 +- doc/handwritten/for-users/BestPractices.en.md | 2 +- doc/handwritten/for-users/CatalogVersioning.en.md | 2 +- doc/handwritten/for-users/CatalogVersioningCI.en.md | 2 +- doc/handwritten/for-users/CatalogVersioningReference.en.md | 2 +- doc/handwritten/for-users/DeterministicTesting.en.md | 2 +- .../for-users/DocumentationExtractionReference.en.md | 2 +- doc/handwritten/for-users/ErrorContext.en.md | 2 +- doc/handwritten/for-users/FAQ.en.md | 2 +- doc/handwritten/for-users/Internationalization.en.md | 2 +- doc/handwritten/for-users/LoggingIntegration.en.md | 2 +- doc/handwritten/for-users/OperationalIntegration.en.md | 2 +- doc/handwritten/for-users/OutcomeGuide.en.md | 2 +- doc/handwritten/for-users/Testing.en.md | 2 +- doc/handwritten/for-users/UsagePatterns.en.md | 2 +- doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md | 2 +- doc/handwritten/for-users/WritingACustomRenderer.en.md | 2 +- doc/handwritten/for-users/WritingErrorMessages.en.md | 2 +- doc/handwritten/for-users/WritingErrorsGuide.en.md | 2 +- 20 files changed, 20 insertions(+), 20 deletions(-) diff --git a/doc/handwritten/for-users/ArbitraryTestValues.en.md b/doc/handwritten/for-users/ArbitraryTestValues.en.md index a85db62..948539b 100644 --- a/doc/handwritten/for-users/ArbitraryTestValues.en.md +++ b/doc/handwritten/for-users/ArbitraryTestValues.en.md @@ -113,7 +113,7 @@ Before reaching for an arbitrary value, verify that: --- <div align="center"> -<a href="DeterministicTesting.en.md">← Deterministic Error Tests</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="OperationalIntegration.en.md">Generating and Publishing the Catalog →</a> +<a href="DeterministicTesting.en.md">← Deterministic Error Tests</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="OperationalIntegration.en.md">Generating and Publishing the Catalog →</a> </div> --- diff --git a/doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md b/doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md index 7581fb0..5192454 100644 --- a/doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md +++ b/doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md @@ -184,7 +184,7 @@ The code remains the source of truth; the pipeline makes that knowledge portable --- <div align="center"> -<a href="CatalogVersioning.en.md">← Catalog Versioning</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="DocumentationExtractionReference.en.md">Extraction and Project Discovery Reference →</a> +<a href="CatalogVersioning.en.md">← Catalog Versioning</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="DocumentationExtractionReference.en.md">Extraction and Project Discovery Reference →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/BestPractices.en.md b/doc/handwritten/for-users/BestPractices.en.md index 183092f..fda2672 100644 --- a/doc/handwritten/for-users/BestPractices.en.md +++ b/doc/handwritten/for-users/BestPractices.en.md @@ -111,7 +111,7 @@ Before merging an error-related change, verify that: --- <div align="center"> -<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="Testing.en.md">Testing Guide →</a> +<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="Testing.en.md">Testing Guide →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/CatalogVersioning.en.md b/doc/handwritten/for-users/CatalogVersioning.en.md index a39320a..c3e10b3 100644 --- a/doc/handwritten/for-users/CatalogVersioning.en.md +++ b/doc/handwritten/for-users/CatalogVersioning.en.md @@ -163,7 +163,7 @@ A rename remains breaking because consumers know the old code. When the title su --- <div align="center"> -<a href="OperationalIntegration.en.md">← CI/CD and Operational Integration</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioningReference.en.md">Command reference →</a> +<a href="OperationalIntegration.en.md">← CI/CD and Operational Integration</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="CatalogVersioningReference.en.md">Command reference →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/CatalogVersioningCI.en.md b/doc/handwritten/for-users/CatalogVersioningCI.en.md index 3c1ac3b..2fc038a 100644 --- a/doc/handwritten/for-users/CatalogVersioningCI.en.md +++ b/doc/handwritten/for-users/CatalogVersioningCI.en.md @@ -214,7 +214,7 @@ This form can produce release notes for the error contract or compare the previo --- <div align="center"> -<a href="CatalogVersioningReference.en.md">← Command reference</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="ArchitectureOfTheDocumentationPipeline.en.md">Architecture of the Documentation Pipeline →</a> +<a href="CatalogVersioningReference.en.md">← Command reference</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="ArchitectureOfTheDocumentationPipeline.en.md">Architecture of the Documentation Pipeline →</a> </div> --- diff --git a/doc/handwritten/for-users/CatalogVersioningReference.en.md b/doc/handwritten/for-users/CatalogVersioningReference.en.md index 3d2a62f..e10c5b4 100644 --- a/doc/handwritten/for-users/CatalogVersioningReference.en.md +++ b/doc/handwritten/for-users/CatalogVersioningReference.en.md @@ -147,7 +147,7 @@ The `catalog update` and `catalog diff` commands accept, among others: --- <div align="center"> -<a href="CatalogVersioning.en.md">← Catalog versioning guide</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioningCI.en.md">CI/CD integration →</a> +<a href="CatalogVersioning.en.md">← Catalog versioning guide</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="CatalogVersioningCI.en.md">CI/CD integration →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/DeterministicTesting.en.md b/doc/handwritten/for-users/DeterministicTesting.en.md index 5fd4a17..e7f68a5 100644 --- a/doc/handwritten/for-users/DeterministicTesting.en.md +++ b/doc/handwritten/for-users/DeterministicTesting.en.md @@ -203,7 +203,7 @@ Before approving a deterministic error test, verify that: --- <div align="center"> -<a href="Testing.en.md">← Testing Outcomes and Errors</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="ArbitraryTestValues.en.md">Arbitrary Test Values →</a> +<a href="Testing.en.md">← Testing Outcomes and Errors</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="ArbitraryTestValues.en.md">Arbitrary Test Values →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/DocumentationExtractionReference.en.md b/doc/handwritten/for-users/DocumentationExtractionReference.en.md index 34c01f4..b933380 100644 --- a/doc/handwritten/for-users/DocumentationExtractionReference.en.md +++ b/doc/handwritten/for-users/DocumentationExtractionReference.en.md @@ -280,7 +280,7 @@ When expected errors are missing, walk the pipeline in order — each step depen --- <div align="center"> -<a href="ArchitectureOfTheDocumentationPipeline.en.md">← Architecture of the Documentation Pipeline</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingACustomRenderer.en.md">Writing a custom renderer →</a> +<a href="ArchitectureOfTheDocumentationPipeline.en.md">← Architecture of the Documentation Pipeline</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="WritingACustomRenderer.en.md">Writing a custom renderer →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/ErrorContext.en.md b/doc/handwritten/for-users/ErrorContext.en.md index e253d09..b13ebdf 100644 --- a/doc/handwritten/for-users/ErrorContext.en.md +++ b/doc/handwritten/for-users/ErrorContext.en.md @@ -173,7 +173,7 @@ If the answer is yes to all six, it is a strong context candidate. --- <div align="center"> -<a href="CoreConcepts.en.md">← Core Concepts</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingErrorsGuide.en.md">Writing Errors Guide →</a> +<a href="CoreConcepts.en.md">← Core Concepts</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="WritingErrorsGuide.en.md">Writing Errors Guide →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/FAQ.en.md b/doc/handwritten/for-users/FAQ.en.md index e0af048..ab2b3bd 100644 --- a/doc/handwritten/for-users/FAQ.en.md +++ b/doc/handwritten/for-users/FAQ.en.md @@ -130,7 +130,7 @@ See [Error Taxonomy and Composition](ErrorTaxonomy.en.md). --- <div align="center"> -<a href="Internationalization.en.md">← Internationalization</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> +<a href="Internationalization.en.md">← Internationalization</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> </div> --- diff --git a/doc/handwritten/for-users/Internationalization.en.md b/doc/handwritten/for-users/Internationalization.en.md index 2739818..21a7edf 100644 --- a/doc/handwritten/for-users/Internationalization.en.md +++ b/doc/handwritten/for-users/Internationalization.en.md @@ -250,7 +250,7 @@ Before publishing localized catalogs, verify that: --- <div align="center"> -<a href="WritingACustomRenderer.en.md">← Writing a custom renderer</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="FAQ.en.md">FAQ →</a> +<a href="WritingACustomRenderer.en.md">← Writing a custom renderer</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="FAQ.en.md">FAQ →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/LoggingIntegration.en.md b/doc/handwritten/for-users/LoggingIntegration.en.md index 9dbee02..7e2732b 100644 --- a/doc/handwritten/for-users/LoggingIntegration.en.md +++ b/doc/handwritten/for-users/LoggingIntegration.en.md @@ -267,7 +267,7 @@ Before approving a logging integration, verify that: --- <div align="center"> -<a href="OperationalIntegration.en.md">← Generating and Publishing the Catalog</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioning.en.md">Catalog Versioning →</a> +<a href="OperationalIntegration.en.md">← Generating and Publishing the Catalog</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="CatalogVersioning.en.md">Catalog Versioning →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/OperationalIntegration.en.md b/doc/handwritten/for-users/OperationalIntegration.en.md index 12807d6..fc75625 100644 --- a/doc/handwritten/for-users/OperationalIntegration.en.md +++ b/doc/handwritten/for-users/OperationalIntegration.en.md @@ -237,7 +237,7 @@ Before approving a catalog-delivery pipeline, verify that: --- <div align="center"> -<a href="ArbitraryTestValues.en.md">← Arbitrary Test Values</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="LoggingIntegration.en.md">Integrate FirstClassErrors with Structured Logging →</a> +<a href="ArbitraryTestValues.en.md">← Arbitrary Test Values</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="LoggingIntegration.en.md">Integrate FirstClassErrors with Structured Logging →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/OutcomeGuide.en.md b/doc/handwritten/for-users/OutcomeGuide.en.md index 4e6823a..eec289a 100644 --- a/doc/handwritten/for-users/OutcomeGuide.en.md +++ b/doc/handwritten/for-users/OutcomeGuide.en.md @@ -241,7 +241,7 @@ Before approving an `Outcome` flow, verify that: --- <div align="center"> -<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="BestPractices.en.md">Best Practices →</a> +<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="BestPractices.en.md">Best Practices →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/Testing.en.md b/doc/handwritten/for-users/Testing.en.md index fdcd5f8..f33d83a 100644 --- a/doc/handwritten/for-users/Testing.en.md +++ b/doc/handwritten/for-users/Testing.en.md @@ -166,7 +166,7 @@ Before approving an error test, verify that: --- <div align="center"> -<a href="BestPractices.en.md">← Best Practices</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="DeterministicTesting.en.md">Deterministic Error Tests →</a> +<a href="BestPractices.en.md">← Best Practices</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="DeterministicTesting.en.md">Deterministic Error Tests →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/UsagePatterns.en.md b/doc/handwritten/for-users/UsagePatterns.en.md index 641d441..193fa26 100644 --- a/doc/handwritten/for-users/UsagePatterns.en.md +++ b/doc/handwritten/for-users/UsagePatterns.en.md @@ -199,7 +199,7 @@ Choose the contract from the first list, the error type from the second, and the --- <div align="center"> -<a href="WritingErrorsGuide.en.md">← Writing Errors Guide</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="OutcomeGuide.en.md">Composing with Outcome →</a> +<a href="WritingErrorsGuide.en.md">← Writing Errors Guide</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="OutcomeGuide.en.md">Composing with Outcome →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md b/doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md index d003dc6..c9ef858 100644 --- a/doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md +++ b/doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md @@ -73,7 +73,7 @@ The goal of this library is not to make every exception richer. It is to make me --- <div align="center"> -<a href="DesignPrinciples.en.md">← Design Principles</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="CoreConcepts.en.md">Core Concepts →</a> +<a href="DesignPrinciples.en.md">← Design Principles</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="CoreConcepts.en.md">Core Concepts →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/WritingACustomRenderer.en.md b/doc/handwritten/for-users/WritingACustomRenderer.en.md index 57e4dfc..a930983 100644 --- a/doc/handwritten/for-users/WritingACustomRenderer.en.md +++ b/doc/handwritten/for-users/WritingACustomRenderer.en.md @@ -307,7 +307,7 @@ Before publishing a renderer, verify that: --- <div align="center"> -<a href="DocumentationExtractionReference.en.md">← Extraction and Project Discovery Reference</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="Internationalization.en.md">Internationalization →</a> +<a href="DocumentationExtractionReference.en.md">← Extraction and Project Discovery Reference</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="Internationalization.en.md">Internationalization →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/WritingErrorMessages.en.md b/doc/handwritten/for-users/WritingErrorMessages.en.md index 7a9758d..d416dab 100644 --- a/doc/handwritten/for-users/WritingErrorMessages.en.md +++ b/doc/handwritten/for-users/WritingErrorMessages.en.md @@ -212,7 +212,7 @@ For the stable title, description, rule, diagnostics, and examples, return to [W --- <div align="center"> -<a href="WritingErrorsGuide.en.md">← Writing Error Documentation</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="UsagePatterns.en.md">Usage Patterns →</a> +<a href="WritingErrorsGuide.en.md">← Writing Error Documentation</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="UsagePatterns.en.md">Usage Patterns →</a> </div> --- \ No newline at end of file diff --git a/doc/handwritten/for-users/WritingErrorsGuide.en.md b/doc/handwritten/for-users/WritingErrorsGuide.en.md index 325059e..ef65400 100644 --- a/doc/handwritten/for-users/WritingErrorsGuide.en.md +++ b/doc/handwritten/for-users/WritingErrorsGuide.en.md @@ -218,7 +218,7 @@ For choosing public and internal runtime text, continue with [Writing Error Mess --- <div align="center"> -<a href="ErrorContext.en.md">← Error Context Guide</a> · <a href="../../../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingErrorMessages.en.md">Writing Error Messages →</a> +<a href="ErrorContext.en.md">← Error Context Guide</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="WritingErrorMessages.en.md">Writing Error Messages →</a> </div> --- \ No newline at end of file