Skip to content

Commit 9791cfa

Browse files
fredbifredbi
authored
docs: more documentation, scrubbed existing docs (#37)
Signed-off-by: Frederic BIDON <[email protected]>
1 parent 6fd3bdf commit 9791cfa

File tree

21 files changed

+2558
-140
lines changed

21 files changed

+2558
-140
lines changed

‎README.md‎

Lines changed: 37 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414

1515
**The v2 our tests wanted**
1616

17-
A set of `go` packages that provide tools for testifying that your code behaves as you intended.
17+
A set of `go` packages that provide tools for testifying (verifying) that your code behaves as you intended.
1818

1919
This is the go-openapi fork of the great [testify](https://github.com/stretchr/testify) package.
2020

@@ -25,7 +25,7 @@ Main features:
2525

2626
* zero external dependencies
2727
* opt-in dependencies for extra features (e.g. asserting YAML, colorized output)
28-
* assertions using generic types (see [a basic example][example-with-generics-url])
28+
* assertions using generic types (see [a basic example][example-with-generics-url]). [Read the fully story with generics][doc-generics]
2929
* [searchable documentation][doc-url]
3030

3131
## Announcements
@@ -40,26 +40,42 @@ Or join our Slack channel: [![Slack Channel][slack-logo]![slack-badge]][slack-ur
4040

4141
### Status
4242

43-
Design and exploration phase. Contributions and proposals are welcome.
43+
Design and exploration phase. Feedback, contributions and proposals are welcome.
4444

4545
> **Recent news**
46-
> Fully refactored how assertions are generated and documented.
47-
> Fixed hangs & panics when using `spew`. Fuzzed `spew`.
48-
> Fixed go routine leaks with `EventuallyWithT` and co.
49-
> Added `Kind` & `NotKind`
50-
> Fix deterministic order of keys in diff
51-
> Fixed edge cases with `InDelta`, `InEpsilon`
52-
> Added opt-in support for colorized output
53-
> Introduced generics (round 1): 16 new type-safe assertions with generic types (added benchmark)
5446
>
55-
> See our [ROADMAP][roadmap].
47+
> ✅ Fully refactored how assertions are generated and documented.
48+
>
49+
> ✅ Fixed hangs & panics when using `spew`. Fuzzed `spew`.
50+
>
51+
> ✅ Fixed go routine leaks with `EventuallyWithT` and co.
52+
>
53+
> ✅ Added `Kind` & `NotKind`
54+
>
55+
> ✅ Fix deterministic order of keys in diff
56+
>
57+
> ✅ Fixed edge cases with `InDelta`, `InEpsilon`
58+
>
59+
> ✅ Fixed edge cases with `EqualValues`
60+
>
61+
> ✅ Fixed wrong logic with `IsNonIncreasing`, `InNonDecreasing`
62+
>
63+
> ✅ Added opt-in support for colorized output
64+
>
65+
> ✅ Introduced generics: 38 new type-safe assertions with generic types (doc: added usage guide, examples and benchmark)
66+
>
67+
> See also our [ROADMAP][doc-roadmap].
68+
69+
## Getting started
5670

57-
## Import this library in your project
71+
Import this library in your project like so.
5872

5973
```cmd
6074
go get github.com/go-openapi/testify/v2
6175
```
6276

77+
... and start writing tests. Look at our [examples][doc-examples].
78+
6379
## Basic usage
6480

6581
`testify` simplifies your test assertions like so.
@@ -123,9 +139,10 @@ distributed with this fork, including internalized libraries.
123139

124140
## Other documentation
125141

126-
* [Getting started](https://go-openapi.github.io/testify/examples/)
142+
* [Getting started][doc-examples]
143+
* [Usage](https://go-openapi.github.io/testify/usage/)
127144
* [Motivations](https://go-openapi.github.io/testify/project/readme)
128-
* [Roadmap][roadmap]
145+
* [Roadmap][doc-roadmap]
129146
* [Internal architecture](https://go-openapi.github.io/testify/project/maintainers/architecture)
130147

131148
* [All-time contributors](./CONTRIBUTORS.md)
@@ -138,15 +155,15 @@ distributed with this fork, including internalized libraries.
138155

139156
Maintainers can cut a new release by either:
140157

141-
* running [this workflow](https://github.com/go-openapi/testify/actions/workflows/bump-release.yml) (recommended)
158+
* running [this workflow][ci-release-workflow] (recommended)
142159
* or :
143160
1. preparing go.mod files with the next tag, merge
144161
2. pushing a semver tag
145162
* signed tags are preferred
146163
* The tag message is prepended to release notes
147164

148165
<!-- Doc links -->
149-
[roadmap]: https://go-openapi.github.io/testify/project/maintainers/roadmap
166+
[doc-roadmap]: https://go-openapi.github.io/testify/project/maintainers/roadmap
150167
<!-- Badges: status -->
151168
[test-badge]: https://github.com/go-openapi/testify/actions/workflows/go-test.yml/badge.svg
152169
[test-url]: https://github.com/go-openapi/testify/actions/workflows/go-test.yml
@@ -169,6 +186,8 @@ Maintainers can cut a new release by either:
169186
<!-- Badges: documentation & support -->
170187
[doc-badge]: https://img.shields.io/badge/doc-site-blue?link=https%3A%2F%2Fgo-openapi.github.io%2Ftestify%2F
171188
[doc-url]: https://go-openapi.github.io/testify
189+
[doc-examples]: https://go-openapi.github.io/testify/usage/examples
190+
[doc-generics]: https://go-openapi.github.io/testify/usage/generics
172191
[example-with-generics-url]: https://go-openapi.github.io/testify#usage-with-generics
173192
[godoc-badge]: https://pkg.go.dev/badge/github.com/go-openapi/testify
174193
[godoc-url]: http://pkg.go.dev/github.com/go-openapi/testify
@@ -186,3 +205,4 @@ Maintainers can cut a new release by either:
186205
[goversion-url]: https://github.com/go-openapi/testify/blob/master/go.mod
187206
[top-badge]: https://img.shields.io/github/languages/top/go-openapi/testify
188207
[commits-badge]: https://img.shields.io/github/commits-since/go-openapi/testify/latest
208+
[ci-release-workflow]: https://github.com/go-openapi/testify/actions/workflows/bump-release.yml

‎SECURITY.md‎

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,30 @@ This policy outlines the commitment and practices of the go-openapi maintainers
88
| ------- | ------------------ |
99
| 2.1.x | :white_check_mark: |
1010

11+
## Vulnerability checks in place
12+
13+
This repository uses automated vulnerability scans, at every merged commit and at least once a week.
14+
15+
We use:
16+
17+
* [`GitHub CodeQL`][codeql-url]
18+
* [`trivy`][trivy-url]
19+
* [`govulncheck`][govulncheck-url]
20+
21+
Reports are centralized in github security reports and visible only to the maintainers.
22+
1123
## Reporting a vulnerability
1224

1325
If you become aware of a security vulnerability that affects the current repository,
14-
please report it privately to the maintainers.
26+
**please report it privately to the maintainers**
27+
rather than opening a publicly visible GitHub issue.
28+
29+
Please follow the instructions provided by github to [Privately report a security vulnerability][github-guidance-url].
1530

16-
Please follow the instructions provided by github to
17-
[Privately report a security vulnerability](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability).
31+
> [!NOTE]
32+
> On Github, navigate to the project's "Security" tab then click on "Report a vulnerability".
1833
19-
TL;DR: on Github, navigate to the project's "Security" tab then click on "Report a vulnerability".
34+
[codeql-url]: https://github.com/github/codeql
35+
[trivy-url]: https://trivy.dev/docs/latest/getting-started
36+
[govulncheck-url]: https://go.dev/blog/govulncheck
37+
[github-guidance-url]: https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability

‎all-docs.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Documentation map
2+
3+
## internals
4+
5+
* ./hack/doc-site/hugo/README.md
6+
* ./internal/difflib/README.md
7+
* ./internal/spew/README.md
8+
* ./internal/testintegration/README.md
9+
10+
## repo
11+
12+
* [x] ./README.md
13+
* [x] ./CONTRIBUTORS.md
14+
* [x] ./.github/CONTRIBUTING.md
15+
* [x] ./.github/DCO.md
16+
* [x] ./CODE_OF_CONDUCT.md
17+
* [x] ./SECURITY.md
18+
19+
## site
20+
21+
### API docs (generated)
22+
23+
* ./docs/doc-site/api/yaml.md
24+
* ./docs/doc-site/api/number.md
25+
* ./docs/doc-site/api/_index.md
26+
* ./docs/doc-site/api/panic.md
27+
* ./docs/doc-site/api/string.md
28+
* ./docs/doc-site/api/equality.md
29+
* ./docs/doc-site/api/file.md
30+
* ./docs/doc-site/api/boolean.md
31+
* ./docs/doc-site/api/common.md
32+
* ./docs/doc-site/api/ordering.md
33+
* ./docs/doc-site/api/json.md
34+
* ./docs/doc-site/api/collection.md
35+
* ./docs/doc-site/api/time.md
36+
* ./docs/doc-site/api/comparison.md
37+
* ./docs/doc-site/api/error.md
38+
* ./docs/doc-site/api/testing.md
39+
* ./docs/doc-site/api/type.md
40+
* ./docs/doc-site/api/http.md
41+
* ./docs/doc-site/api/condition.md
42+
43+
### project docs
44+
45+
* [x] ./docs/doc-site/_index.md
46+
47+
* [x] ./docs/doc-site/usage/_index.md
48+
* ./docs/doc-site/usage/TUTORIAL.md
49+
* ./docs/doc-site/usage/EXAMPLES.md
50+
* ./docs/doc-site/usage/GENERICS.md
51+
* [x] ./docs/doc-site/usage/CHANGES.md
52+
53+
* [x] ./docs/doc-site/project/_index.md
54+
* [x] ./docs/doc-site/project/LICENSE.md
55+
* [x] ./docs/doc-site/project/NOTICE.md
56+
* [x] ./docs/doc-site/project/maintainers/_index.md
57+
* [x] ./docs/doc-site/project/maintainers/MAINTAINERS.md
58+
* ./docs/doc-site/project/maintainers/ARCHITECTURE.md
59+
* ./docs/doc-site/project/maintainers/CODEGEN.md
60+
* [x] ./docs/doc-site/project/maintainers/BENCHMARKS.md
61+
* [x] ./docs/doc-site/project/maintainers/ROADMAP.md
62+
* ./docs/doc-site/project/maintainers/ORIGINAL.md
63+
* ./docs/doc-site/project/README.md
64+
* [x] ./docs/doc-site/project/SECURITY.md
65+
* ./docs/doc-site/project/contributing/STYLE.md
66+
* [x] ./docs/doc-site/project/contributing/CONTRIBUTING.md
67+
* [x] ./docs/doc-site/project/contributing/_index.md
68+
* [x] ./docs/doc-site/project/contributing/CONTRIBUTORS.md
69+
* [x] ./docs/doc-site/project/contributing/DCO.md
70+
* [x] ./docs/doc-site/project/contributing/CODE_OF_CONDUCT.md

‎codegen/internal/generator/templates/doc_index.md.gotmpl‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ weight: 1
99
modified: {{ date }}
1010
---
1111

12-
**Go testing assertions for the rest of us**
12+
**The v2 our tests wanted**
1313

1414
The [`testify/v2`][testifyv2] package has a fairly large API surface.
1515

@@ -25,7 +25,7 @@ with all documented exported variants documented in a more concise form than the
2525

2626
## Domains
2727

28-
The `testify` API is organized in {{ .RefCount }} domains shown below.
28+
The `testify` API is organized in {{ .RefCount }} logical domains shown below.
2929
Each domain contains assertions regrouped by their use case (e.g. http, json, error).
3030

3131
{{ print "{{" }}< children type="card" description="true" >{{ print "}}" }}

‎docs/doc-site/_index.md‎

Lines changed: 34 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -18,43 +18,44 @@ This is the go-openapi fork of the great [testify](https://github.com/stretchr/t
1818
### Status
1919

2020
{{% button href="https://github.com/go-openapi/testify/fork" hint="fork me on github" style=primary icon=code-fork %}}Fork me{{% /button %}}
21-
Design and exploration phase. Contributions and proposals are welcome.
21+
Design and exploration phase. Feedback, contributions and proposals are welcome.
2222

2323
### Motivation
2424

2525
From the maintainers of `testify`, it looks like a v2 will eventually be released, but they'll do it at their own pace.
2626

27-
We like all the principles they put forward to build this v2. [See discussion about v2](https://github.com/stretchr/testify/discussions/1560)
27+
We like all the principles they exposed to build this v2. [See discussion about v2](https://github.com/stretchr/testify/discussions/1560).
2828

2929
However, at `go-openapi` we would like to address the well-known issues in `testify` with different priorities.
3030

3131
With this fork, we want to:
32-
1. remove all external dependencies.
33-
2. make it easy to maintain and extend.
34-
3. pare down some of the chrome that has been added over the years.
32+
1. [x] remove all external dependencies.
33+
2. [x] make it easy to maintain and extend.
34+
3. [x] pare down some of the chrome that has been added over the years.
3535

3636
{{% notice style="primary" title="Extended hand" icon="hand" %}}
3737
We hope that this endeavor will help the original project with a live-drill of what a v2 could look like.
38-
Hopefully, some of our ideas here will eventually percolate back into the original project.
3938

40-
We are always happy to discuss with people who face the same problems as we do: avoid breaking changes,
39+
Hopefully, some of our ideas will eventually percolate back into the original project and help the wider
40+
community of go developers write better, clearer test code.
41+
42+
Feedback is welcome and we are always happy to discuss with people who face the same problems as we do: avoid breaking changes,
4143
APIs that became bloated over a decade or so, uncontrolled dependencies, difficult choices when it comes to introduce
4244
breaking changes, conflicting demands from users etc.
4345
{{% /notice %}}
4446

45-
More about our motivations in the project's [README](README.md#motivation).
46-
47+
Find more about our motivations in the project's [README](README.md#motivation).
4748
You might also be curious about our [ROADMAP](project/maintainers/ROADMAP.md).
4849

4950
### Getting started
5051

51-
To use this package in your projects:
52+
Import this library in your project like so.
5253

5354
```cmd
5455
go get github.com/go-openapi/testify/v2
5556
```
5657

57-
... and start writing tests. Look at our [examples](./examples/).
58+
... and start writing tests. Look at our [examples][doc-examples].
5859

5960
### Basic usage
6061

@@ -109,6 +110,23 @@ A formatted variant suffixed with `Tf` is also exposed.
109110

110111
Obviously, the `Assertion` type cannot be extended with generic methods, as of `go1.25`.
111112

113+
{{< cards >}}
114+
{{% card title="EqualT" %}}
115+
```go
116+
import (
117+
"testing"
118+
119+
"github.com/go-openapi/testify/v2/require"
120+
)
121+
...
122+
123+
const expected = "Hello World"
124+
var input := "World"
125+
126+
result := someRamblingTextGeneration(input)
127+
require.EqualT(t, expected, result)
128+
```
129+
{{% /card %}}
112130
{{% card title="InDeltaT" %}}
113131
```go
114132
import (
@@ -128,6 +146,7 @@ Obviously, the `Assertion` type cannot be extended with generic methods, as of `
128146
require.InDeltaT(t, expected, input, delta)
129147
```
130148
{{% /card %}}
149+
{{< /cards >}}
131150

132151
## Licensing
133152

@@ -140,17 +159,16 @@ distributed with this fork, including internalized libraries.
140159

141160
## Contributing
142161

143-
Please feel free to submit issues, fork the repository and send pull requests!
144-
145-
When submitting an issue, we ask that you please include a complete test function that demonstrates the issue.
146-
Extra credit for those using Testify to write the test code that demonstrates it.
162+
Feel free to submit issues, fork the repository and send pull requests!
147163

148164
{{% notice style="primary" title="Info" icon="info" %}}
149165
Code generation is used. Run `go generate ./...` to update generated files.
150166
{{% /notice %}}
151167

152-
See also the [CONTRIBUTING guidelines](./project/contributing/CONTRIBUTING.md).
168+
See also our [CONTRIBUTING guidelines](./project/contributing/CONTRIBUTING.md).
153169

154170
---
155171

156172
{{< children type="card" description="true" >}}
173+
174+
[doc-examples]: ./usage/examples

‎docs/doc-site/examples/_index.md‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎docs/doc-site/project/SECURITY.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ We use:
2323
* [`trivy`][trivy-url]
2424
* [`govulncheck`][govulncheck-url]
2525

26-
Reports are centralized in github security reports and visible to the maintainers.
26+
Reports are centralized in github security reports and visible only to the maintainers.
2727

2828
## Reporting a vulnerability
2929

0 commit comments

Comments
 (0)