more CONTRIBUTING etc docs

* fixes #6

Signed-off-by: Frédéric BIDON <[email protected]>

Author: fredbi

.github/CONTRIBUTING.md

@@ -1,42 +1,124 @@
 ## Contribution Guidelines
 
+You'll find below general guidelines, which mostly correspond to standard practices for open sourced repositories.
+
+>**TL;DR**
+>
+> If you're a seasoned go developer on github, then you should just feel at home with us and you may skip
+> the rest of this document. This is just 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).
+
+### Asking questions
+
+You may inquire about anything 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.
+
 ### 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 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.
+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.
 
-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.
+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
+
+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).
+
+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 instal 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 `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.
+
+#### Tests
 
-- 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.
+Submit unit tests for your changes.
 
-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.
+Go has a great built-in test framework ; use it!
 
-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.
+Take a look at existing tests for inspiration, and run the full test suite on your branch
+before submitting a pull request.
 
-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.
+#### Code style
+
+You may read our stance on code style [there](../docs/STYLE.md).
+
+#### Documentation
+
+Update the documentation when creating or modifying features.
+
+The documentation for the go-openapi packages is found on the public go docs site:
+
+<https://pkg.go.dev/github.com/go-openapi/jsonpointer>
+
+Test your documentation changes for clarity, concision, and correctness, as
+well as a clean documentation build.
+
+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.
@@ -47,26 +129,32 @@ 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.
 
+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.
+
+#### 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. 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`.
 
-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.
+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
 
-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 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.
+
+The rules are pretty simple: if you can certify the below (from
 [developercertificate.org](http://developercertificate.org/)):
 
 ```
@@ -115,3 +203,18 @@ then you just add a line to every git commit message:
 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`.
+
+> Notice that at this moment, we do not require commits to be PGP-signed.
+
+## Issue Triage [![Open Source Helpers](https://www.codetriage.com/go-swagger/go-swagger/badges/users.svg)](https://www.codetriage.com/go-swagger/go-swagger)
+
+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
+
+If you would like to start triaging issues, one easy way to get started is to
+[subscribe to go-swagger on CodeTriage](https://www.codetriage.com/go-swagger/go-swagger).
+
+> Disclaimer: the go-swagger maintainers have no affiliation with `www.codetriage.com`.

.golangci.yml

@@ -3,13 +3,9 @@ linters:
   default: all
   disable:
     - depguard
-    - errorlint
-    - exhaustruct
     - funlen
     - godox
-    - gosmopolitan
-    - ireturn
-    - lll
+    - exhaustruct
     - nlreturn
     - nonamedreturns
     - noinlineerr
@@ -32,6 +28,11 @@ linters:
       max-complexity: 20
     gocyclo:
       min-complexity: 20
+    exhaustive:
+      default-signifies-exhaustive: true
+      default-case-required: true
+    lll:
+      line-length: 180
   exclusions:
     generated: lax
     presets:
@@ -47,6 +48,7 @@ formatters:
   enable:
     - gofmt
     - goimports
+    - gofumpt
   exclusions:
     generated: lax
     paths:

docs/MAINTAINERS.md

@@ -0,0 +1,62 @@
+# Coding style at `go-openapi`
+
+> **TL;DR**
+>
+
+## Meta-linter
+
+Universally formatted go code promotes ease of writing, reading, and maintenance.
+
+You should run `golangci-lint run` before committing your changes.
+
+Many editors have plugins that do that automatically.
+
+> We use the `golangci-lint` meta-linter. The configuration lies in `.golangci-lint.yml`.
+> You may read <https://golangci-lint.run/docs/linters/configuration/>  for additional reference.
+
+## Linting rules posture
+
+Thanks to go's original design, we developers don't have to waste much time arguing about code figures of style.
+
+We enable all linters published by `golangci-lint` by default, then disable a few ones.
+
+Here are the reasons why they are disabled:
+
+```yaml
+  disable:
+    - depguard              # we don't want to configure rules to constrain import. 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
+    - godox                 # we don't see any value in forbidding TODO's etc in code
+    - nlreturn
+    - nonamedreturns
+    - noinlineerr           # there is no value added forbidding inlined err
+    - paralleltest          # we like parallel tests. We just don't want this to be enforced everywhere.
+    - recvcheck             # we like the idea of having pointer and non-pointer receivers
+    - testpackage           # we like test packages. We just don't want it to be enforced everywhere.
+    - tparallel             # see paralleltest
+    - varnamelen            # sometimes, we like short variables
+    - whitespace            # no added value
+    - wrapcheck             # although there is some sense with this linter's general idea, it produces too much noise
+    - wsl                   # no added value. Noise.
+    - wsl_v5                # no added value. Noise.
+```
+
+Enabled linters with relaxed constraints:
+```yaml
+  settings:
+    dupl:
+      threshold: 200        # in a older code base such as ours, we have to be tolerant with a little redundancy
+    goconst:
+      min-len: 2
+      min-occurrences: 3
+    cyclop:
+      max-complexity: 20    # the default is too low for most of our functions. 20 is a nicer trade-off
+    gocyclo:
+      min-complexity: 20
+    exhaustive:             # when using default in switch, this should be good enough
+      default-signifies-exhaustive: true
+      default-case-required: true
+    lll:
+      line-length: 180      # we just want to avoid extremely long lines. It is no big deal if a line or two don't fit on your terminal.
+```

docs/STYLE.md

@@ -54,7 +54,7 @@ type JSONSetable interface {
 // # Limitations
 //
 //   - Unlike go standard marshaling, untagged fields do not default to the go field name and are ignored.
-//   - anonymous embedded fields are not
+//   - anonymous embedded fields are not traversed
 type Pointer struct {
 	referenceTokens []string
 }
@@ -251,7 +251,7 @@ func (p *Pointer) resolveNodeForToken(node any, decodedToken string, nameProvide
 	rValue := reflect.Indirect(reflect.ValueOf(node))
 	kind := rValue.Kind()
 
-	switch kind { //nolint:exhaustive
+	switch kind {
 	case reflect.Struct:
 		nm, ok := nameProvider.GetGoNameForType(rValue.Type(), decodedToken)
 		if !ok {
@@ -294,7 +294,7 @@ func isNil(input any) bool {
 	}
 
 	kind := reflect.TypeOf(input).Kind()
-	switch kind { //nolint:exhaustive
+	switch kind {
 	case reflect.Pointer, reflect.Map, reflect.Slice, reflect.Chan:
 		return reflect.ValueOf(input).IsNil()
 	default:
@@ -338,7 +338,7 @@ func getSingleImpl(node any, decodedToken string, nameProvider *jsonname.NamePro
 		return getSingleImpl(*typed, decodedToken, nameProvider)
 	}
 
-	switch kind { //nolint:exhaustive
+	switch kind {
 	case reflect.Struct:
 		nm, ok := nameProvider.GetGoNameForType(rValue.Type(), decodedToken)
 		if !ok {
@@ -389,7 +389,7 @@ func setSingleImpl(node, data any, decodedToken string, nameProvider *jsonname.N
 		return ns.JSONSet(decodedToken, data)
 	}
 
-	switch rValue.Kind() { //nolint:exhaustive
+	switch rValue.Kind() {
 	case reflect.Struct:
 		nm, ok := nameProvider.GetGoNameForType(rValue.Type(), decodedToken)
 		if !ok {
@@ -462,7 +462,7 @@ func offsetSingleObject(dec *json.Decoder, decodedToken string) (int64, error) {
 func offsetSingleArray(dec *json.Decoder, decodedToken string) (int64, error) {
 	idx, err := strconv.Atoi(decodedToken)
 	if err != nil {
-		return 0, fmt.Errorf("token reference %q is not a number: %v: %w", decodedToken, err, ErrPointer)
+		return 0, fmt.Errorf("token reference %q is not a number: %w: %w", decodedToken, err, ErrPointer)
 	}
 	var i int
 	for i = 0; i < idx && dec.More(); i++ {

pointer.go

@@ -471,6 +471,7 @@ func (s settableDoc) MarshalJSON() ([]byte, error) {
 	res.D = s.Int
 	return json.Marshal(res)
 }
+
 func (s *settableDoc) UnmarshalJSON(data []byte) error {
 	var res struct {
 		A settableColl `json:"a"`
@@ -550,6 +551,7 @@ type settableColl struct {
 func (s settableColl) MarshalJSON() ([]byte, error) {
 	return json.Marshal(s.Items)
 }
+
 func (s *settableColl) UnmarshalJSON(data []byte) error {
 	return json.Unmarshal(data, &s.Items)
 }
@@ -583,6 +585,7 @@ type settableInt struct {
 func (s settableInt) MarshalJSON() ([]byte, error) {
 	return json.Marshal(s.Value)
 }
+
 func (s *settableInt) UnmarshalJSON(data []byte) error {
 	return json.Unmarshal(data, &s.Value)
 }