doc: improved documentation

.github/CONTRIBUTING.md

@@ -1,72 +1,195 @@
 ## Contribution Guidelines
 
+You'll find below general guidelines, which mostly correspond to standard practices for open sourced repositories.
+
+>**TL;DR**
+>
+> If you're already an experience 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.
+
+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](../docs).
+
+## Questions & Issues
+
+### Asking questions
+
+You may inquire about anything about this library by reporting a "Question" issue on github.
+
+### 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.
+
+### Triaging issues
+
+You can help triage issues which may include:
+
+* reproducing bug reports
+* asking for important information, such as version numbers or reproduction instructions
+* answering questions and sharing your insight in issue comments
+
+## Code contributions
+
 ### Pull requests are always welcome
 
-We are always thrilled to receive pull requests, and do our best to
-process them as fast as possible. Not sure if that typo is worth a pull
-request? Do it! We will appreciate it.
+We are always thrilled to receive pull requests, and we do our best to
+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 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.
+
+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,
+but everybody can use it to do just about everything related to OpenAPI.
+
+This means that we might decide against incorporating a new feature.
+
+However, there might be a way to implement that feature *on top of* our libraries.
+
+### Environment
 
-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.
+You just need a `go` compiler to be installed. No special tools are needed to work with our libraries.
 
-We're trying very hard to keep go-swagger lean and focused. We don't want it
-to do everything for everybody. This means that we might decide against
-incorporating a new feature. However, there might be a way to implement
-that feature *on top of* go-swagger.
+The go compiler version required is always the old stable (latest minor go version - 1).
 
+If you're already 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.
+
+If you don't have it, you may install it like so:
+
+```sh
+go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
+```
 
 ### Conventions
 
-Fork the repo and make changes on your fork in a feature branch:
+#### Git flow
+
+Fork the repo and make changes to your fork in a feature branch.
+
+To submit a pull request, push your branch to your fork (e.g. `upstream` remote):
+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 XXX-something where XXX is the number of the
-  issue
-- If it's a feature branch, create an enhancement issue to announce your
-  intentions, and name it XXX-something where XXX is the number of the issue.
+- if it's a bugfix 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.
 
-Submit unit tests for your changes.  Go has a great test framework built in; use
-it! Take a look at existing tests for inspiration. Run the full test suite on
-your branch before submitting a pull request.
+> NOTE: we don't enforce naming conventions on branches: it's your fork after all.
 
-Update the documentation when creating or modifying features. Test
-your documentation changes for clarity, concision, and correctness, as
-well as a clean documentation build. See ``docs/README.md`` for more
-information on building the docs and how docs get released.
+#### Tests
 
-Write clean code. Universally formatted code promotes ease of writing, reading,
-and maintenance. Always run `gofmt -s -w file.go` on each changed file before
-committing your changes. Most editors have plugins that do this automatically.
+Submit unit tests for your changes.
+
+Go has a great built-in test framework ; use it!
+
+Take a look at existing tests for inspiration, and run the full test suite on your branch
+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.
+
+#### 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.
+
+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:
+
+<https://pkg.go.dev/github.com/go-openapi/jsonpointer>
+
+Check your documentation changes for clarity, concision, and correctness.
+
+If you want to assess the rendering of your changes when published to `pkg.go.dev`, you may
+want to install the `pkgsite` tool proposed by `golang.org`.
+
+```sh
+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.
+
+#### Commit messages
 
 Pull requests descriptions should be as clear as possible and include a
 reference to all the issues that they address.
 
 Pull requests must not contain commits from other users or branches.
 
-Commit messages must start with a capitalized and short summary (max. 50
-chars) written in the imperative, followed by an optional, more detailed
-explanatory text which is separated from the summary by an empty line.
+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" ...).
+
+The title in your commit message is used directly to produce our release notes: try to keep them neat.
+
+The commit message body should detail your changes.
+
+If an issue should be closed by a commit, please add this reference in the commit body:
+
+```
+* fixes #{issue number}
+```
+
+#### Code review
+
+Code review comments may be added to your pull request.
+
+Discuss, then make the suggested modifications and push additional commits to your feature branch.
+
+Be sure to post a comment after pushing. The new commits will show up in the pull
+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**
+using `git rebase -i` and `git push -f`.
+
+After every commit the test suite should be passing.
 
-Code review comments may be added to your pull request. Discuss, then make the
-suggested modifications and push additional commits to your feature branch. Be
-sure to post a comment after pushing. The new commits will show up in the pull
-request automatically, but the reviewers will not be notified unless you
-comment.
+Include documentation changes in the same commit so that a revert would remove all traces of the feature or fix.
 
-Before the pull request is merged, make sure that you squash your commits into
-logical units of work using `git rebase -i` and `git push -f`. After every
-commit the test suite should be passing. Include documentation changes in the
-same commit so that a revert would remove all traces of the feature or fix.
+#### Sign your work
 
-Commits that fix or close an issue should include a reference like `Closes #XXX`
-or `Fixes #XXX`, which will automatically close the issue when merged.
+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.
 
-### Sign your work
+We require the simple DCO below with an email signing your commit.
+PGP-signed commit are greatly appreciated but not required.
 
-The sign-off is a simple line at the end of the explanation for the
-patch, which certifies that you wrote it or otherwise have the right to
-pass it on as an open-source patch.  The rules are pretty simple: if you
-can certify the below (from
+The rules are pretty simple: if you can certify the below (from
 [developercertificate.org](http://developercertificate.org/)):
 
 ```

README.md

@@ -3,14 +3,13 @@
 <!-- Badges: status  -->
 [![Tests][test-badge]][test-url] [![Coverage][cov-badge]][cov-url] [![CI vuln scan][vuln-scan-badge]][vuln-scan-url] [![CodeQL][codeql-badge]][codeql-url]
 <!-- Badges: release & docker images  -->
-[![Release][release-badge]][release-url]
 <!-- Badges: code quality  -->
-[![Go Report Card][gocard-badge]][gocard-url] [![CodeFactor Grade][codefactor-badge]][codefactor-url]
 <!-- Badges: license & compliance -->
-[![License][license-badge]][license-url]
+[![Release][release-badge]][release-url] [![Go Report Card][gocard-badge]][gocard-url] [![CodeFactor Grade][codefactor-badge]][codefactor-url] [![License][license-badge]][license-url]
 <!-- Badges: documentation & support -->
 <!-- Badges: others & stats -->
-[![GoDoc][godoc-badge]][godoc-url] [![Slack Channel][slack-badge]][slack-url] [![go version][goversion-badge]][goversion-url] ![Top language][top-badge] ![Commits since latest release][commits-badge]
+<!-- Slack badge disabled until I am able to restore a valid link to the chat -->
+[![GoDoc][godoc-badge]][godoc-url] <!-- [![Slack Channel][slack-badge]][slack-url] -->[![go version][goversion-badge]][goversion-url] ![Top language][top-badge] ![Commits since latest release][commits-badge]
 
 ---
 
@@ -28,13 +27,18 @@ go get github.com/go-openapi/jsonpointer
 
 ## Basic usage
 
-See [examples](./examples_test.go)
+See also some [examples](./examples_test.go)
+
+### Retrieving a value
 
 ```go
   import (
     "github.com/go-openapi/jsonpointer"
   )
 
+
+  var doc any
+
   ...
 
 	pointer, err := jsonpointer.New("/foo/1")
@@ -50,6 +54,23 @@ See [examples](./examples_test.go)
   ...
 ```
 
+### Setting a value
+
+```go
+  ...
+  var doc any
+  ...
+	pointer, err := jsonpointer.New("/foo/1")
+	if err != nil {
+		... // error: e.g. invalid JSON pointer specification
+  }
+
+	doc, err = p.Set(doc, "value")
+	if err != nil {
+		... // error: e.g. key not found, index out of bounds, etc.
+	}
+```
+
 ## Change log
 
 See <https://github.com/go-openapi/jsonpointer/releases>
@@ -96,7 +117,7 @@ using the special trailing character "-" is not implemented.
 <!-- Badges: documentation & support -->
 [doc-badge]: https://img.shields.io/badge/doc-site-blue?link=https%3A%2F%2Fgoswagger.io%2Fgo-openapi%2F
 [doc-url]: https://goswagger.io/go-openapi
-[godoc-badge]: https://pkg.go.dev/github.com/go-openapi/jsonpointer?status.svg
+[godoc-badge]: https://pkg.go.dev/badge/github.com/go-openapi/jsonpointer
 [godoc-url]: http://pkg.go.dev/github.com/go-openapi/jsonpointer
 [slack-badge]: https://slackin.goswagger.io/badge.svg
 [slack-url]: https://slackin.goswagger.io

docs/MAINTAINERS.md

@@ -0,0 +1,44 @@
+# Maintainer's guide
+
+**DRAFT**
+
+(to be completed)
+
+## Repo configuration
+
+* branch protection
+* required PR checks
+* auto-merge feature
+
+## Continuous Integration
+
+### Code Quality checks
+
+* meta-linter: golangci-lint
+* linter config
+
+* Code quality assessment: CodeFactor
+* Code quality badges
+  * go report card
+  * CodeFactor
+
+### Testing
+
+* test reports
+* test coverage reports
+
+### Automated updates
+
+* dependabot
+
+* go version udpates
+
+### Vulnerability scanners
+
+* github CodeQL
+* trivy
+* govulnscan
+
+## Releases
+
+* release notes generator: git-cliff