The CONTRIBUTING.md file is mixing a couple of different topics:
Setting up a development environment
Build instructions
How to install from sources
Instructions for maintainers (how to release, how cross-arch testing works)
And it is also missing some important information:
What's expected in PRs
How people wanting to contribute should communicate with us
The later is probably the most important information for the CONTRIBUTING.md file, as it is shown to users when trying to contribute by opening a PR or an issue.
Proposed solution
Split the CONTRIBUTING.md file into:
DEVELOPMENT.md: Instructions on setting up a development environment, how to run the tests and build instructions. Anything related to development that is useful even if you are not planning to contribute back.
maintainers-guide.md (in docs/): Instructions for maintainers (how to release, how cross-arch testing works in the CI, etc.)
CONTRIBUTING.md: Instructions on how to contribute back. For example:
How to contact us
How should you write commit messages
How to write release notes
How to write tests and how much tests we expect in PRs
What to do before even opening a PR (like create an issue or discussion to make sure the PR has chances to get accepted)
Explain how to sign commits, and to add a sign-off-by, what DCO is and why we require all of this
Check-list for PRs, like running nox, writing tests, writing release notes
What's needed?
The
CONTRIBUTING.mdfile is mixing a couple of different topics:And it is also missing some important information:
The later is probably the most important information for the
CONTRIBUTING.mdfile, as it is shown to users when trying to contribute by opening a PR or an issue.Proposed solution
Split the
CONTRIBUTING.mdfile into:DEVELOPMENT.md: Instructions on setting up a development environment, how to run the tests and build instructions. Anything related to development that is useful even if you are not planning to contribute back.maintainers-guide.md(indocs/): Instructions for maintainers (how to release, how cross-arch testing works in the CI, etc.)CONTRIBUTING.md: Instructions on how to contribute back. For example:nox, writing tests, writing release notesWe should probably also add a documentation top-level section
Developers, where we could group these 3 documents into different sections. Like:Additional context