doc: announced new discord channel

.github/CONTRIBUTING.md

@@ -1,114 +1,211 @@
 ## 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 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.
+
+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).
+
+## How can I contribute?
+
+There are many ways in which you can contribute. 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
+
+## 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
+
+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 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're already used to work with `go` you should already have everything in place.
 
-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.
+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 `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
+
+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
 
-- 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.
+You may read our stance on code style [there](../docs/STYLE.md).
 
-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.
+#### Documentation
 
-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.
+Don't forget to update the documentation when creating or modifying features.
 
-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.
+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" ...).
 
-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.
+The title in your commit message is used directly to produce our release notes: try to keep them neat.
 
-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.
+The commit message body should detail your changes.
 
-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.
+If an issue should be closed by a commit, please add this reference in the commit body:
 
-### Sign your work
+```
+* fixes #{issue number}
+```
 
-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
-[developercertificate.org](http://developercertificate.org/)):
+#### Code review
 
-```
-Developer Certificate of Origin
-Version 1.1
+Code review comments may be added to your pull request.
 
-Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
-660 York Street, Suite 102,
-San Francisco, CA 94110 USA
+Discuss, then make the suggested modifications and push additional commits to your feature branch.
 
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
+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`.
 
-Developer's Certificate of Origin 1.1
+After every commit the test suite should be passing.
 
-By making a contribution to this project, I certify that:
+Include documentation changes in the same commit so that a revert would remove all traces of the feature or fix.
 
-(a) The contribution was created in whole or in part by me and I
-    have the right to submit it under the open source license
-    indicated in the file; or
+#### Sign your work
 
-(b) The contribution is based upon previous work that, to the best
-    of my knowledge, is covered under an appropriate open source
-    license and I have the right under that license to submit that
-    work with modifications, whether created in whole or in part
-    by me, under the same open source license (unless I am
-    permitted to submit under a different license), as indicated
-    in the file; or
+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.
 
-(c) The contribution was provided directly to me by some other
-    person who certified (a), (b) or (c) and I have not modified
-    it.
+We require the simple DCO below with an email signing your commit.
+PGP-signed commit are greatly appreciated but not required.
 
-(d) I understand and agree that this project and the contribution
-    are public and that a record of the contribution (including all
-    personal information I submit with it, including my sign-off) is
-    maintained indefinitely and may be redistributed consistent with
-    this project or the open source license(s) involved.
-```
+The rules are pretty simple:
 
-then you just add a line to every git commit message:
+* 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
 
     Signed-off-by: Joe Smith <joe@gmail.com>
 

.github/DCO.md

@@ -0,0 +1,40 @@
+ # Developer's Certificate of Origin
+
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+660 York Street, Suite 102,
+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:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```