docs: updated README for a better communication of the contents

README.md

@@ -21,12 +21,25 @@ This is the go-openapi fork of the great [testify](https://github.com/stretchr/t
 > [!NOTE]
 > This is the home of `github.com/go-openapi/testify/v2`, an active, opinionated fork of `github.com/stretchr/testify`.
 
-Main features:
-
-* zero external dependencies
-* opt-in dependencies for extra features (e.g. asserting YAML, colorized output)
-* assertions using generic types (see [a basic example][example-with-generics-url]). [Read the fully story with generics][doc-generics]
-* [searchable documentation][doc-url]
+## Why choose `go-openapi/testify/v2`
+
+* 95% compatible with `stretchr/testify` — if you already use it, our migration tool automates the switch
+* Actively maintained: regular fixes and evolutions, many PRs proposed upstream are already in
+* Zero external dependencies — you import what you need, with opt-in modules for extras (e.g. YAML, colorized output)
+* Modernized codebase targeting go1.24+
+* Go routine leak detection built in: zero-setup, no false positives, works with parallel tests (unlike `go.uber.org/goleak`)
+* File descriptor leak detection (linux-only)
+* Type-safe assertions with generics (see [a basic example][example-with-generics-url]) — migration to generics can be automated too. [Read the full story][doc-generics]
+* Safe async assertions, extended JSON & YAML assertions
+* Coming in `v2.5.0`: non-flaky async assertions using `synctest`, and internal tools exposed as standalone modules (spew, unified diff, goleak)
+* We take documentation seriously: [searchable doc site][doc-url] with testable examples and a complete tutorial, plus detailed [godoc][godoc-url] for every assertion
+
+### This fork isn't for everyone
+
+* You need the `mock` package — we removed it and won't bring it back. For suites, we're [open to discussion][suite-discussion] about a redesigned approach
+* Your project must support Go versions older than 1.24
+* You rely on `testifylint` or other tooling that expects the `stretchr/testify` import path
+* You need 100% API compatibility — we're at 95%, and the remaining 5% are intentional removals
 
 ## Announcements
 
@@ -174,6 +187,7 @@ Maintainers can cut a new release by either:
 
 <!-- Doc links -->
 [doc-roadmap]: https://go-openapi.github.io/testify/project/maintainers/roadmap
+[suite-discussion]: https://github.com/go-openapi/testify/discussions/75
 <!-- Badges: status  -->
 [test-badge]: https://github.com/go-openapi/testify/actions/workflows/go-test.yml/badge.svg
 [test-url]: https://github.com/go-openapi/testify/actions/workflows/go-test.yml

docs/doc-site/project/README.md

@@ -3,6 +3,7 @@ title: README
 description: |
   Introducing go-openapi/testify/v2.
 
+  - Why choose testify/v2
   - Approach
   - Main features
   - Differences with v1
@@ -11,6 +12,26 @@ weight: 2
 
 **The v2 our tests wanted**
 
+## Why choose `go-openapi/testify/v2`
+
+* 95% compatible with `stretchr/testify` — if you already use it, our migration tool automates the switch
+* Actively maintained: regular fixes and evolutions, many PRs proposed upstream are already in
+* Zero external dependencies — you import what you need, with opt-in modules for extras (e.g. YAML, colorized output)
+* Modernized codebase targeting go1.24+
+* Go routine leak detection built in: zero-setup, no false positives, works with parallel tests (unlike `go.uber.org/goleak`)
+* File descriptor leak detection (linux-only)
+* Type-safe assertions with generics (see [a basic example](../usage/EXAMPLES.md)) — migration to generics can be automated too. [Read the full story](../usage/GENERICS.md)
+* Safe async assertions, extended JSON & YAML assertions
+* Coming in `v2.5.0`: non-flaky async assertions using `synctest`, and internal tools exposed as standalone modules (spew, unified diff, goleak)
+* We take documentation seriously: [searchable doc site](../../api/) with testable examples and a complete tutorial, plus detailed [godoc][godoc-url] for every assertion
+
+### This fork isn't for everyone
+
+* You need the `mock` package — we removed it and won't bring it back. For suites, we're [open to discussion](https://github.com/go-openapi/testify/discussions/75) about a redesigned approach
+* Your project must support Go versions older than 1.24
+* You rely on `testifylint` or other tooling that expects the `stretchr/testify` import path
+* You need 100% API compatibility — we're at 95%, and the remaining 5% are intentional removals
+
 ## Motivation
 
 See [why we wanted a v2](./MOTIVATION.md).

docs/doc-site/project/contributing/STYLE.md

@@ -74,12 +74,12 @@ Here are the reasons why they are disabled (update: Feb. 2026, `golangci-lint v2
 
 ```yaml
   disable:
-    - depguard              # we don't want to configure rules to constrain import. That's the reviewer's job
+    - depguard              # we don't want to configure rules to constrain imports. That's the reviewer's job
     - exhaustruct           # we don't want to configure regexp's to check type name. That's the reviewer's job
-    - funlen                # we accept cognitive complexity as a meaningful metric, but function length is relevant
+    - funlen                # we accept cognitive complexity as a meaningful metric, but function length is not relevant
     - godox                 # we don't see any value in forbidding TODO's etc in code
     - nlreturn              # we usually apply this "blank line" rule to make code less compact. We just don't want to enforce it
-    - nonamedreturns        # we don't see any valid reason why we couldn't used named returns
+    - nonamedreturns        # we don't see any valid reason why we couldn't use named returns
     - noinlineerr           # there is no value added forbidding inlined err
     - paralleltest          # we like parallel tests. We just don't want them to be enforced everywhere
     - recvcheck             # we like the idea of having pointer and non-pointer receivers