doc: aligned project documentation

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

.github/CONTRIBUTING.md

@@ -1,48 +1,57 @@
-## Contribution Guidelines
+You'll find here general guidelines to contribute to this project.
+They mostly correspond to standard practices for open source repositories.
 
-You'll find below general guidelines, which mostly correspond to standard practices for open sourced repositories.
+We have tried to keep things as simple as possible.
 
->**TL;DR**
->
-> If you're already an experienced go developer on github, then you should just feel at home with us
+> [!NOTE]
+> If you're an experienced go developer on github, then you should just feel at home with us
 > and you may well skip the rest of this document.
 >
-> You'll essentially find the usual guideline for a go library project on github.
+> You'll essentially apply the usual guidelines for a go library project on github.
+
+These guidelines are common to all libraries published on github by the `go-openapi` organization,
+so you'll feel at home with any of our projects.
 
-These guidelines are general to all libraries published on github by the `go-openapi` organization.
+You'll find more detailed (or repo-specific) instructions in the [maintainer's docs][maintainers-doc].
 
-You'll find more detailed (or repo-specific) instructions in the [maintainer's docs](../docs).
+[maintainers-doc]: ../docs/MAINTAINERS.md
 
-## How can I contribute?
+## How can I contribute
 
-There are many ways in which you can contribute. Here are a few ideas:
+There are many ways in which you can contribute, not just code. Here are a few ideas:
 
- * Reporting Issues / Bugs
- * Suggesting Improvements
- * Code
-   * bug fixes and new features that are within the main project scope
-   * improving test coverage
-   * addressing code quality issues
- * Documentation
- * Art work that makes the project look great
+- Reporting issues or bugs
+- Suggesting improvements
+- Documentation
+- Art work that makes the project look great
+- Code
+    - proposing bug fixes and new features that are within the main project scope
+    - improving test coverage
+    - addressing code quality issues
 
 ## Questions & issues
 
-### Asking questions
+### Asking a question
+
+You may inquire anything about this library by reporting a "Question" issue on github.
 
-You may inquire about anything about this library by reporting a "Question" issue on github.
+You may also join our discord server where you may discuss issues or requests.
+
+[![Discord Server][discord-badge]][discord-url]
+
+[discord-badge]: https://img.shields.io/discord/1446918742398341256?logo=discord&label=discord&color=blue
+[discord-url]: https://discord.gg/twZ9BwT3
 
 ### Reporting issues
 
 Reporting a problem with our libraries _is_ a valuable contribution.
-
 You can do this on the github issues page of this repository.
 
 Please be as specific as possible when describing your issue.
 
 Whenever relevant, please provide information about your environment (go version, OS).
 
-Adding a code snippet to reproduce the issue is great, and as a big time saver for maintainers.
+Adding a code snippet to reproduce the issue is great, and a big time saver for maintainers.
 
 ### Triaging issues
 
@@ -62,14 +71,16 @@ process them as fast as possible.
 Not sure if that typo is worth a pull request? Do it! We will appreciate it.
 
 If your pull request is not accepted on the first try, don't be discouraged!
-If there's a problem with the implementation, hopefully you received feedback on what to improve.
+If there's a problem with the implementation, hopefully you've received feedback on what to improve.
 
 If you have a lot of ideas or a lot of issues to solve, try to refrain a bit and post focused
 pull requests.
-Think that they must be reviewed by a maintainer and it is easy to lost track of things on big PRs.
+Think that they must be reviewed by a maintainer and it is easy to lose track of things on big PRs.
 
 We're trying very hard to keep the go-openapi packages lean and focused.
-These packages constitute a toolkit: it won't do everything for everybody out of the box,
+
+Together, these packages constitute a toolkit for go developers:
+it won't do everything for everybody out of the box,
 but everybody can use it to do just about everything related to OpenAPI.
 
 This means that we might decide against incorporating a new feature.
@@ -80,9 +91,11 @@ However, there might be a way to implement that feature *on top of* our librarie
 
 You just need a `go` compiler to be installed. No special tools are needed to work with our libraries.
 
-The go compiler version required is always the old stable (latest minor go version - 1).
+The minimal go compiler version required is always the old stable (latest minor go version - 1).
+
+Our libraries are designed and tested to work on `Linux`, `MacOS` and `Windows`.
 
-If you're already used to work with `go` you should already have everything in place.
+If you're used to work with `go` you should already have everything in place.
 
 Although not required, you'll be certainly more productive with a local installation of `golangci-lint`,
 the meta-linter our CI uses.
@@ -104,12 +117,12 @@ github will propose to open a pull request on the original repository.
 
 Typically you'd follow some common naming conventions:
 
-- if it's a bugfix branch, name it `fix/XXX-something`where XXX is the number of the
+- if it's a bug fixing branch, name it `fix/XXX-something` where XXX is the number of the
   issue on github
 - if it's a feature branch, create an enhancement issue to announce your
   intentions, and name it `feature/XXX-something` where XXX is the number of the issue.
 
-> NOTE: we don't enforce naming conventions on branches: it's your fork after all.
+NOTE: we don't enforce naming conventions on branches: it's your fork after all.
 
 #### Tests
 
@@ -121,24 +134,24 @@ Take a look at existing tests for inspiration, and run the full test suite on yo
 before submitting a pull request.
 
 Our CI measures test coverage and the test coverage of every patch.
+
 Although not a blocking step - because there are so many special cases -
 this is an indicator that maintainers consider when approving a PR.
-
-Please try your best to cover about 80% of your patch.
+Please try your best to cover at least 80% of your patch.
 
 #### Code style
 
 You may read our stance on code style [there](../docs/STYLE.md).
 
 #### Documentation
 
-Don't forget to update the documentation when creating or modifying features.
+Don't forget to update the documentation when creating or modifying a feature.
 
 Most documentation for this library is directly found in code as comments for godoc.
 
-The documentation for the go-openapi packages is published on the public go docs site:
+The documentation for this go-openapi package is published on [the public go docs site][go-doc].
 
-<https://pkg.go.dev/github.com/go-openapi/jsonpointer>
+---
 
 Check your documentation changes for clarity, concision, and correctness.
 
@@ -150,11 +163,14 @@ go install golang.org/x/pkgsite/cmd/pkgsite@latest
 ```
 
 Then run on the repository folder:
+
 ```sh
 pkgsite .
 ```
 
-This wil run a godoc server locally where you may see the documentation generated from your local repository.
+This will run a godoc server locally where you may see the documentation generated from your local repository.
+
+[go-doc]: https://pkg.go.dev/github.com/go-openapi/analysis
 
 #### Commit messages
 
@@ -164,7 +180,7 @@ reference to all the issues that they address.
 Pull requests must not contain commits from other users or branches.
 
 Commit messages are not required to follow the "conventional commit" rule, but it's certainly a good
-thing to follow this guidelinea (e.g. "fix: blah blah", "ci: did this", "feat: did that" ...).
+thing to follow that convention (e.g. "fix: fixed panic in XYZ", "ci: did this", "feat: did that" ...).
 
 The title in your commit message is used directly to produce our release notes: try to keep them neat.
 
@@ -186,7 +202,7 @@ Be sure to post a comment after pushing. The new commits will show up in the pul
 request automatically, but the reviewers will not be notified unless you comment.
 
 Before the pull request is merged,
-**make sure that you squash your commits into logical units of work**
+**make sure that you've squashed your commits into logical units of work**
 using `git rebase -i` and `git push -f`.
 
 After every commit the test suite should be passing.
@@ -195,6 +211,8 @@ Include documentation changes in the same commit so that a revert would remove a
 
 #### Sign your work
 
+Software is developed by real people.
+
 The sign-off is a simple line at the end of your commit message,
 which certifies that you wrote it or otherwise have the right to
 pass it on as an open-source patch.
@@ -204,11 +222,30 @@ PGP-signed commit are greatly appreciated but not required.
 
 The rules are pretty simple:
 
-* read our [DCO](./DCO.md) (from [developercertificate.org](http://developercertificate.org/))
-* if you agree with these terms, then you just add a line to every git commit message
+- read our [DCO][dco-doc] (from [developercertificate.org][dco-source])
+- if you agree with these terms, then you just add a line to every git commit message
 
-    Signed-off-by: Joe Smith <joe@gmail.com>
+```
+Signed-off-by: Joe Smith <joe@gmail.com>
+```
 
 using your real name (sorry, no pseudonyms or anonymous contributions.)
 
-You can add the sign off when creating the git commit via `git commit -s`.
+You can add the sign-off when creating the git commit via `git commit -s`.
+
+[dco-doc]: ./DCO.md
+[dco-source]: https://developercertificate.org
+
+## Code contributions by AI agents
+
+Our agentic friends are welcome to contribute!
+
+We only have a few demands to keep-up with human maintainers.
+
+1. Issues and PRs written or posted by agents should always mention the original (human) poster for reference
+2. We don't accept PRs attributed to agents. We don't want commits signed like "author: @claude.code".
+   Agents or bots may coauthor commits, though.
+3. Security vulnerability reports by agents should always be reported privately and mention the original (human) poster
+   (see also [Security Policy][security-doc]).
+
+[security-doc]: ../SECURITY.md

.github/DCO.md

@@ -1,4 +1,4 @@
- # Developer's Certificate of Origin
+# Developer's Certificate of Origin
 
 ```
 Developer Certificate of Origin
@@ -11,7 +11,6 @@ San Francisco, CA 94110 USA
 Everyone is permitted to copy and distribute verbatim copies of this
 license document, but changing it is not allowed.
 
-
 Developer's Certificate of Origin 1.1
 
 By making a contribution to this project, I certify that:

.github/wordlist.txt

@@ -1,37 +1,73 @@
 BasePath
 CLI
+CodeFactor
+CodeQL
+DCO
 ExternalDocs
+GoDoc
 JSON
 JSONschema
 LiftAllOfs
+OAI
+PR's
+PRs
 PropagateNameExtensions
 RemoveUnused
+SPDX
 TODO
+Triaging
+UI
 Unmarshalling
+XYZ
 additionalProperties
+agentic
 allOf
 analysed
+ci
+codebase
+codecov
 codegen
 collable
+config
 defs
+dependabot
+dev
+developercertificate
 dpath
 enums
+fka
+github
+godoc
 golang
+golangci
 https
 indexable
 inlined
 inoperant
+kubectl
+linter's
+linters
+maintainer's
+md
 mediatypes
+metalinter
 mixin
 mixins
+monorepo
 omitempty
 openapi
 param
 params
+prepended
 preprocessing
 rebases
+repo
+repos
 schemas
+semver
+sexualized
 statuscode
 unmarshalling
 unmarshals
+vuln
 yaml

CODE_OF_CONDUCT.md

@@ -23,7 +23,9 @@ include:
 Examples of unacceptable behavior by participants include:
 
 * The use of sexualized language or imagery and unwelcome sexual attention or
+
 advances
+
 * Trolling, insulting/derogatory comments, and personal or political attacks
 * Public or private harassment
 * Publishing others' private information, such as a physical or electronic
@@ -55,7 +57,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at ivan+abuse@flanders.co.nz. All
+reported by contacting the project team at <ivan+abuse@flanders.co.nz>. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.
@@ -68,7 +70,7 @@ members of the project's leadership.
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at [http://contributor-covenant.org/version/1/4][version]
+available at [<http://contributor-covenant.org/version/1/4>][version]
 
 [homepage]: http://contributor-covenant.org
 [version]: http://contributor-covenant.org/version/1/4/