From 0fd3097defcfd838b6b39de394e6b1cdbe0f7ba6 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 10 Aug 2026 18:19:10 +0000 Subject: [PATCH] docs: state the support boundaries, ADR outcomes and baseline lifecycle The reference described these three in prose that a reader had to reconstruct. Give each the shape it is actually read in: a per-artifact table of build target and supported host, a table of the four ADR-check outcomes and the action each requires, and the four steps a GenDoc baseline goes through. Salvaged from agent/extract-adr-specifications, whose separate specification pages this reference had already superseded. Every claim was re-verified against the current tree: target frameworks, roll-forward policies, RoslynFloorVersion, and the fce catalog subcommands. --- .../adr-implementation-reference.fr.md | 28 +++++++++++++++++++ .../adr-implementation-reference.md | 28 +++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/doc/handwritten/for-maintainers/specifications/adr-implementation-reference.fr.md b/doc/handwritten/for-maintainers/specifications/adr-implementation-reference.fr.md index 76f61ca4..fa613c03 100644 --- a/doc/handwritten/for-maintainers/specifications/adr-implementation-reference.fr.md +++ b/doc/handwritten/for-maintainers/specifications/adr-implementation-reference.fr.md @@ -27,6 +27,14 @@ Les outils en ligne de commande et le worker hors processus ciblent le plus anci Les bibliothèques netstandard2.0 ont un plancher distinct : .NET Framework 4.7.2. Des tests Windows dédiés exercent les bibliothèques concernées sur le véritable runtime .NET Framework. Les projets d'outillage restent réservés au .NET moderne. +Les frontières qui en résultent, par artefact livré : + +| Artefact | Cible de build | Frontière d'hôte prise en charge | +|---|---|---| +| `FirstClassErrors`, `FirstClassErrors.Testing`, `FirstClassErrors.RequestBinder` | `netstandard2.0` | .NET Framework 4.7.2 ou ultérieur, et tout .NET moderne implémentant .NET Standard 2.0 | +| `FirstClassErrors.Analyzers` | `netstandard2.0`, compilé contre `RoslynFloorVersion` | les versions de SDK et de Visual Studio portant ce Roslyn, ou ultérieures | +| `FirstClassErrors.Cli`, `FirstClassErrors.GenDoc`, `FirstClassErrors.GenDoc.Worker` | `net8.0` | .NET 8 ou ultérieur, par roll-forward | + ## Vérification ADR des pull requests Décision liée : [ADR-0004](../adr/0004-check-every-pull-request-against-the-adr-base.fr.md). @@ -35,6 +43,17 @@ La vérification ADR est une procédure destinée au mainteneur et aux agents, d Le workflow GitHub actuel est déclenché manuellement. Il soutient donc la procédure, mais ne garantit pas à lui seul que chaque pull request a été vérifiée. Toute automatisation future de cette obligation relève de la documentation et de la configuration des workflows, pas de l'ADR-0004. +La vérification a quatre issues possibles, chacune assortie d'une action requise : + +| Issue | Action requise | +|---|---| +| Aucune décision | Indiquer que la modification n'introduit aucune décision d'architecture. | +| Créer | Rédiger un ADR par décision nouvelle, au statut `Proposed`, l'indexer et le lier depuis la pull request. | +| Superséder | Rédiger un successeur au statut `Proposed` et nommer l'ADR accepté qu'il remplacerait ; ne jamais réécrire l'ADR accepté. | +| Alerter | Signaler le conflit exact avec un ADR accepté et laisser la résolution au mainteneur. | + +Un agent rédige et recommande ; seul le mainteneur accepte, supersède, déprécie ou lève un conflit. + ## Contrats d'implémentation du Request Binder Décisions liées : [ADR-0007](../adr/0007-name-the-binder-terminals-new-and-create.fr.md), [ADR-0008](../adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.fr.md), [ADR-0012](../adr/0012-fix-the-binder-options-before-binding-begins.fr.md), [ADR-0014](../adr/0014-bind-a-required-list-by-presence-not-cardinality.fr.md), [ADR-0017](../adr/0017-provide-a-configurable-application-wide-default-for-the-binder-options.fr.md), [ADR-0018](../adr/0018-bundle-the-binders-structural-error-code-and-messages.fr.md), [ADR-0019](../adr/0019-document-overridden-binder-errors-in-the-consumers-catalog.fr.md), [ADR-0021](../adr/0021-bind-out-of-dto-arguments-as-peers-through-a-source-agnostic-entry.fr.md). @@ -55,6 +74,15 @@ Le catalogue d'erreurs généré est traité comme un artefact de compatibilité La baseline n'est mise à jour par le processus de release qu'après une publication compatible réussie. Les étapes de workflow, commandes, chemins d'artefacts et procédures de reprise sont maintenus dans la référence des workflows. Les mainteneurs doivent notamment prendre en compte le cas où la publication réussit mais où la mise à jour suivante de la baseline échoue. +Cycle de vie de la baseline : + +1. la baseline versionnée représente le catalogue de la dernière release `cli` publiée avec succès ; +2. la génération de documentation en pull request compare le catalogue courant à cette baseline et expose l'impact en attente pour la revue ; +3. la baseline n'avance pas au cours du développement ordinaire ; +4. après une publication `cli` réussie, l'automatisation de release la régénère depuis l'état livré et commite le résultat sur `main`. + +La baseline n'est générée que par `fce catalog update` ; l'éditer à la main invalide le contrat mesuré. + ## Contrats de génération de JustDummies Décisions liées : [ADR-0006](../adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md), [ADR-0011](../adr/0011-host-dummies-as-a-standalone-package.fr.md), [just-dummies ADR-0004](https://github.com/Reefact/just-dummies/blob/main/doc/handwritten/for-maintainers/adr/0004-gate-distinct-collections-by-cardinality-else-bounded-draw.md), [just-dummies ADR-0005](https://github.com/Reefact/just-dummies/blob/main/doc/handwritten/for-maintainers/adr/0005-cap-any-combine-at-arity-eight.md), [just-dummies ADR-0006](https://github.com/Reefact/just-dummies/blob/main/doc/handwritten/for-maintainers/adr/0006-materialize-dummies-only-through-generate.md). diff --git a/doc/handwritten/for-maintainers/specifications/adr-implementation-reference.md b/doc/handwritten/for-maintainers/specifications/adr-implementation-reference.md index 512b45dd..db6c6dea 100644 --- a/doc/handwritten/for-maintainers/specifications/adr-implementation-reference.md +++ b/doc/handwritten/for-maintainers/specifications/adr-implementation-reference.md @@ -27,6 +27,14 @@ The command-line tooling and out-of-process worker target the oldest supported . The netstandard2.0 libraries have a separate support floor: .NET Framework 4.7.2. Dedicated Windows tests exercise the relevant libraries on the real .NET Framework runtime. Tooling projects remain modern-.NET-only. +The resulting boundaries, per shipped artifact: + +| Artifact | Build target | Supported host boundary | +|---|---|---| +| `FirstClassErrors`, `FirstClassErrors.Testing`, `FirstClassErrors.RequestBinder` | `netstandard2.0` | .NET Framework 4.7.2 or later, and any modern .NET implementing .NET Standard 2.0 | +| `FirstClassErrors.Analyzers` | `netstandard2.0`, compiled against `RoslynFloorVersion` | the SDK and Visual Studio releases carrying that Roslyn, or later | +| `FirstClassErrors.Cli`, `FirstClassErrors.GenDoc`, `FirstClassErrors.GenDoc.Worker` | `net8.0` | .NET 8 or later, through roll-forward | + ## ADR pull-request check Related decision: [ADR-0004](../adr/0004-check-every-pull-request-against-the-adr-base.md). @@ -35,6 +43,17 @@ The ADR check is a maintainer and agent procedure, documented in `AGENTS.md`, th The current GitHub workflow is manually dispatchable and therefore supports the procedure but does not, by itself, guarantee that every pull request was checked. Any future automated enforcement belongs in the workflow documentation and configuration rather than ADR-0004. +The check has four possible outcomes, and each carries a required action: + +| Outcome | Required action | +|---|---| +| No decision | State that the change introduces no architectural decision. | +| Create | Draft one ADR per new decision as `Proposed`, index it, and link it from the pull request. | +| Supersede | Draft a successor as `Proposed` and name the accepted ADR it would replace; never rewrite the accepted one. | +| Alert | Flag the exact conflict with an accepted ADR and leave the resolution to the maintainer. | + +An agent drafts and recommends; only the maintainer accepts, supersedes, deprecates, or waives a conflict. + ## Request Binder implementation contracts Related decisions: [ADR-0007](../adr/0007-name-the-binder-terminals-new-and-create.md), [ADR-0008](../adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.md), [ADR-0012](../adr/0012-fix-the-binder-options-before-binding-begins.md), [ADR-0014](../adr/0014-bind-a-required-list-by-presence-not-cardinality.md), [ADR-0017](../adr/0017-provide-a-configurable-application-wide-default-for-the-binder-options.md), [ADR-0018](../adr/0018-bundle-the-binders-structural-error-code-and-messages.md), [ADR-0019](../adr/0019-document-overridden-binder-errors-in-the-consumers-catalog.md), [ADR-0021](../adr/0021-bind-out-of-dto-arguments-as-peers-through-a-source-agnostic-entry.md). @@ -55,6 +74,15 @@ The generated error catalog is treated as a versioned compatibility artifact. Re The baseline is updated only by the release process after a successful compatible release. Workflow steps, commands, artifact paths, and recovery procedures are maintained in the workflow reference. In particular, maintainers must account for the failure mode where publication succeeds but the subsequent baseline update does not. +The baseline's lifecycle: + +1. the committed baseline represents the catalog of the last successfully published `cli` release; +2. pull-request documentation generation compares the current catalog against it and exposes the pending impact for review; +3. the baseline does not advance during ordinary development; +4. after a successful `cli` publication, release automation regenerates it from the shipped state and commits the result to `main`. + +The baseline is generated only through `fce catalog update`; hand-editing it invalidates the measured contract. + ## JustDummies generation contracts Related decisions: [ADR-0006](../adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md), [ADR-0011](../adr/0011-host-dummies-as-a-standalone-package.md), [just-dummies ADR-0004](https://github.com/Reefact/just-dummies/blob/main/doc/handwritten/for-maintainers/adr/0004-gate-distinct-collections-by-cardinality-else-bounded-draw.md), [just-dummies ADR-0005](https://github.com/Reefact/just-dummies/blob/main/doc/handwritten/for-maintainers/adr/0005-cap-any-combine-at-arity-eight.md), [just-dummies ADR-0006](https://github.com/Reefact/just-dummies/blob/main/doc/handwritten/for-maintainers/adr/0006-materialize-dummies-only-through-generate.md).