doc: doc cleanup before v2.3

fredbi · fredbi · commit dd31c23896f8 · 2026-01-27T11:29:07.000+01:00
Signed-off-by: Frederic BIDON &lt;fredbi@yahoo.com&gt;
diff --git a/.mdsf.json b/.mdsf.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/hougesen/mdsf/main/schemas/v0.11.1/mdsf.schema.json",
+  "format_finished_document": false,
+  "languages": {
+    "go": "golangci-lint:fmt",
+    "shell": "shfmt"
+  },
+  "language_aliases": {
+    "sh": "shell",
+    "cmd": "shell",
+    "bash": "shell"
+  }
+}
diff --git a/README.md b/README.md
@@ -122,7 +122,7 @@ thus reducing their dependencies footprint.
 
 Go-swagger will be adapted over Q1 2026.
 
-Features will probably be added to support our main use cases there.
+Features will be added to support our main use cases there.
 
 ## Change log
 
@@ -144,6 +144,7 @@ distributed with this fork, including internalized libraries.
 * [Motivations](https://go-openapi.github.io/testify/project/readme)
 * [Roadmap][doc-roadmap]
 * [Internal architecture](https://go-openapi.github.io/testify/project/maintainers/architecture)
+* [Benchmarks](https://go-openapi.github.io/testify/project/maintainers/benchmarks)
 
 * [All-time contributors](./CONTRIBUTORS.md)
 * [Contributing guidelines](https://go-openapi.github.io/testify/project/contributing/)
diff --git a/SECURITY.md b/SECURITY.md
@@ -6,7 +6,7 @@ This policy outlines the commitment and practices of the go-openapi maintainers
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 2.1.x   | :white_check_mark: |
+| 2.2.x   | :white_check_mark: |
 
 ## Vulnerability checks in place
 
diff --git a/docs/doc-site/_index.md b/docs/doc-site/_index.md
@@ -20,32 +20,11 @@ This is the go-openapi fork of the great [testify](https://github.com/stretchr/t
 {{% button href="https://github.com/go-openapi/testify/fork" hint="fork me on github" style=primary icon=code-fork %}}Fork me{{% /button %}}
 Design and exploration phase. Feedback, contributions and proposals are welcome.
 
-### Motivation
-
-From the maintainers of `testify`, it looks like a v2 will eventually be released, but they'll do it at their own pace.
-
-We like all the principles they exposed to build this v2. [See discussion about v2](https://github.com/stretchr/testify/discussions/1560).
-
-However, at `go-openapi` we would like to address the well-known issues in `testify` with different priorities.
-
-With this fork, we want to:
-1. [x] remove all external dependencies.
-2. [x] make it easy to maintain and extend.
-3. [x] pare down some of the chrome that has been added over the years.
+See our [ROADMAP](./maintainers/ROADMAP.md).
 
-{{% notice style="primary" title="Extended hand" icon="hand" %}}
-We hope that this endeavor will help the original project with a live-drill of what a v2 could look like.
-
-Hopefully, some of our ideas will eventually percolate back into the original project and help the wider 
-community of go developers write better, clearer test code.
-
-Feedback is welcome and we are always happy to discuss with people who face the same problems as we do: avoid breaking changes, 
-APIs that became bloated over a decade or so, uncontrolled dependencies, difficult choices when it comes to introduce
-breaking changes, conflicting demands from users etc.
-{{% /notice %}}
+### Motivation
 
-Find more about our motivations in the project's [README](README.md#motivation).
-You might also be curious about our [ROADMAP](project/maintainers/ROADMAP.md).
+See [why we wanted a v2](./MOTIVATION.md).
 
 ### Getting started
 
@@ -179,6 +158,7 @@ See also our [CONTRIBUTING guidelines](./project/contributing/CONTRIBUTING.md).
 - [Generics Guide](./usage/GENERICS.md) - Type-safe assertions with 38 generic functions
 - [Migration Guide](./usage/MIGRATION.md) - Migrating from stretchr/testify v1
 - [Changes from v1](./usage/CHANGES.md) - All changes and improvements in v2
+- [Benchmarks](./project/maintainers/benchmarks.md) - Performance improvements in v2
 
 **Reference:**
 - [API Reference](./api/_index.md) - Complete assertion catalog organized by domain
diff --git a/docs/doc-site/project/MOTIVATION.md b/docs/doc-site/project/MOTIVATION.md
@@ -0,0 +1,66 @@
+---
+title: Motivation
+description: Motivations for this fork
+weight: 5
+---
+
+From the maintainers of `testify`, it looks like a v2 will eventually be released, but they'll do it at their own pace.
+
+We like all the principles they exposed to build this v2. [See discussion about v2](https://github.com/stretchr/testify/discussions/1560).
+
+However, at `go-openapi` we would like to address the well-known issues in `testify` with different priorities.
+
+With this fork, we want to:
+
+1. [x] remove all external dependencies.
+2. [x] make it easy to maintain and extend.
+3. [x] pare down some of the chrome that has been added over the years.
+
+---
+
+{{% notice style="primary" title="Extended hand" icon="hand" %}}
+We hope that this endeavor will help the original project with a live-drill of what a v2 could look like.
+
+Hopefully, some of our ideas will eventually percolate back into the original project and help the wider 
+community of go developers write better, clearer test code.
+
+Feedback is welcome and we are always happy to discuss with people who face the same problems as we do: avoid breaking changes, 
+APIs that became bloated over a decade or so, uncontrolled dependencies, difficult choices when it comes to introduce
+breaking changes, conflicting demands from users etc.
+{{% /notice %}}
+
+You might also be curious about our [ROADMAP](project/maintainers/ROADMAP.md).
+
+---
+
+1. We wanted first to remove all external dependencies.
+
+> For all our libraries and generated test code we don't want test dependencies
+> to drill farther than `import github.com/go-openapi/testify/v2`, but on some specific (and controlled)
+> occasions.
+>
+> In this fork, all external stuff is either internalized (`go-spew`, `difflib`),
+> removed (`mocks`, `suite`, `http`) or specifically enabled by importing this module
+> (`github.com/go-openapi/testify/enable/yaml/v2`).
+
+2. Make it easy to maintain and extend.
+
+> For go-openapi, testify should just be yet another part of our toolkit.
+> We need it to work, be easily adaptable to our needs and not divert our development effort away from our other repos.
+> This big refactor is an investment.
+
+3. We want to pare down some of the chrome that has been added over the years
+
+> The `go-openapi` libraries and the `go-swagger` project make a rather limited use of the vast API provided by `testify`.
+>
+> With this first version of the fork, we have removed `mocks` and `suite`, which we don't use.
+> They might be added later on, with better controlled dependencies.
+>
+> In the forthcoming maintenance of this fork, much of the "chrome" or "ambiguous" API will be pared down.
+> There is no commitment yet on the stability of the API.
+>
+> Chrome would be added later: we have the "enable" packages just for that for when external dependencies are needed.
+
+4. We want to add new features like generics, more useful assertions for JSON and safety checks.
+
+5. We want to get rid of the API quirks and gotchas that panic or return unexpected results.
diff --git a/docs/doc-site/project/README.md b/docs/doc-site/project/README.md
@@ -1,51 +1,21 @@
 ---
 title: README
 description: |
-  Introducing `go-openapi/testify/v2`.
+  Introducing go-openapi/testify/v2.
 
   - Approach
   - Main features
   - Differences with v1
-weight: 1
+weight: 2
 ---
 
-**Go testing assertions for the rest of us**
+**The v2 our tests wanted**
 
 ## Motivation
 
-1. We want first to remove all external dependencies.
+See [why we wanted a v2](./MOTIVATION.md).
 
-> For all our libraries and generated test code we don't want test dependencies
-> to drill farther than `import github.com/go-openapi/testify/v2`, but on some specific (and controlled)
-> occasions.
->
-> In this fork, all external stuff is either internalized (`go-spew`, `difflib`),
-> removed (`mocks`, `suite`, `http`) or specifically enabled by importing this module
-> (`github.com/go-openapi/testify/enable/yaml/v2`).
-
-2. Make it easy to maintain and extend.
-
-> For go-openapi, testify should just be yet another part of our toolkit.
-> We need it to work, be easily adaptable to our needs and not divert our development effort away from our other repos.
-> This big refactor is an investment that has to pay off.
-
-3. We want to pare down some of the chrome that has been added over the years
-
-> The `go-openapi` libraries and the `go-swagger` project make a rather limited use of the vast API provided by `testify`.
->
-> With this first version of the fork, we have removed `mocks` and `suite`, which we don't use.
-> They might be added later on, with better controlled dependencies.
->
-> In the forthcoming maintenance of this fork, much of the "chrome" or "ambiguous" API will be pared down.
-> There is no commitment yet on the stability of the API.
->
-> Chrome would be added later: we have the "enable" packages just for that.
-
-4. We hope that this endeavor will help the original project with a live-drill of what a v2 could look like.
-   We are always happy to discuss with people who face the same problems as we do: avoid breaking changes, 
-   APIs that became bloated over a decade or so, uncontrolled dependencies, conflicting demands from users etc.
-
-### The approach with this fork
+### Approach with this fork
 
 This fork targets **go1.24**.
 
diff --git a/docs/doc-site/project/SECURITY.md b/docs/doc-site/project/SECURITY.md
@@ -2,7 +2,7 @@
 title: Security Policy
 description: |
   This document outlines the commitment and practices of the go-openapi maintainers regarding security
-weight: 2
+weight: 3
 ---
 
 This policy outlines the commitment and practices of the go-openapi maintainers regarding security.
@@ -11,7 +11,7 @@ This policy outlines the commitment and practices of the go-openapi maintainers
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 2.1.x   | :white_check_mark: |
+| 2.2.x   | :white_check_mark: |
 
 ## Vulnerability checks in place
 
diff --git a/docs/doc-site/project/maintainers/ARCHITECTURE.md b/docs/doc-site/project/maintainers/ARCHITECTURE.md
@@ -4,6 +4,65 @@ description: Project structure
 weight: 2
 ---
 
+## Primer
+
+### Goals
+
+We want the maintainance of dozens of test assertions, times many variants, to remain reasonably low.
+
+The maintainance flow is intended to require different activities and levels of understanding,
+dependending on the complexity of a planned evolution.
+
+{{< mermaid align="center" zoom="true" >}}
+journey
+    section Fixes & minor enhancements
+      internal/assertions:5: Knowledge of the functionality
+    section New dependencies
+      internal/assertions/enable/...:5: Understanding of the repo architecture
+      enable/...:5:  Understanding of the repo architecture
+    section API changes
+      regenerate code:5: No specific knowledge
+    section New constructs to support
+      code & doc generator:5: Knowledge of internals
+{{< /mermaid >}}
+
+Fixes and enhancements propagate naturally to the variants without the need to regenerate code.
+
+### The maths with assertion variants
+
+Each test assertion produces 2 base variants (assert, require).
+
+Each of these variants produces another formatted variant. Except for generic assertions, we produce
+one "forward" variant and one "forward formatted" variant (as methods).
+
+**For every non-generic assertion: 8 variants.**
+
+**For every generic assertion: 4 variants.**
+
+**For every "helper" function (not an assertion): 2 variants.**
+
+
+All these variants make up several hundreds functions, which poses a challenge for maintainance and documentation.
+
+We have adopted code and documentation generation as a mean to mitigate this issue.
+
+#### Current (v2.2.0)
+
+ 1. Generic assertions (with type parameters): 38 functions
+ 2. Non-generic assertions (with t T parameter, no type parameters): 82 functions
+ 3. Helper functions (no t T parameter): 4 functions
+
+ Total: 124 functions to _maintain_
+
+ **Generated Functions**
+
+ 1. Generic assertions: 152
+ 2. Non-generic assertions: 656
+ 3. Helper functions: 8
+ 4. Constructors: 2
+
+ Total: 818 functions
+
 ## Architecture Overview
 
 {{< mermaid align="center" zoom="true" >}}
@@ -31,7 +90,6 @@ All assertion implementations live in `internal/assertions/`, organized by domai
 **Code Generator: `codegen/`**
 
 The generator scans `internal/assertions/` and produces:
-- n assertion functions × 8 variants = 608 generated functions (current: n=76)
 - Package-level functions (`assert.Equal`, `require.Equal`)
 - Format variants (`assert.Equalf`, `require.Equalf`)
 - Forward methods (`a.Equal()`, `r.Equal()`)
@@ -41,6 +99,8 @@ The generator scans `internal/assertions/` and produces:
 
 **Generated Packages: `assert/` and `require/`**
 
+The generated functions directly call the internal implementation: no code duplication or change in semantics.
+
 **Generated Documentation: `docs/doc-site/api/`**
 
 Everything in these packages is generated. Never edit generated files directly.
@@ -57,3 +117,7 @@ The `enable/` package provides optional features that users can activate via bla
 - `enable/colors/` - Activates colorized output via `import _ "github.com/go-openapi/testify/v2/enable/colors"`
 
 These packages are not generated and allow optional dependencies to be isolated from the core library.
+
+## See Also
+
+- [Code generation](./CODEGEN.md) - Detailed view of our code and doc generator
diff --git a/docs/doc-site/project/maintainers/CODEGEN.md b/docs/doc-site/project/maintainers/CODEGEN.md
@@ -77,7 +77,7 @@ This repository uses code generation extensively to maintain consistency across
     style not_generated_require fill:#4a9eff,color:#fff
 {{< /mermaid >}}
 
-> The generator scans source code, extracts metadata, builds a model, and applies templates to generate ~600+ functions, tests, and documentation from ~70-80+ source functions.
+> The generator scans source code, extracts metadata, builds a model, and applies templates to generate ~800+ functions, tests, and documentation from ~100+ source functions.
 
 ---
 
@@ -158,7 +158,9 @@ graph TD
     style require_group fill:#ffb6c1,color:#000
 {{< /mermaid >}}
 
-> **76 functions × 8 variants = 608 generated functions** (plus tests and documentation for each)
+> **reflection-based assertions become 8, generic assertions become 4**
+>
+> (plus tests and documentation for each).
 
 ---
 
diff --git a/docs/doc-site/project/maintainers/ROADMAP.md b/docs/doc-site/project/maintainers/ROADMAP.md
diff --git a/docs/doc-site/usage/CHANGES.md b/docs/doc-site/usage/CHANGES.md
diff --git a/docs/doc-site/usage/MIGRATION.md b/docs/doc-site/usage/MIGRATION.md
diff --git a/docs/doc-site/usage/TRACKING.md b/docs/doc-site/usage/TRACKING.md
