Rework README and CONTRIBUTING

[srittau]

This shuffles sections around between README.md and CONTRIBUTING.md. CONTRIBUTING now contains information pertaining to opening PRs, README all other information. I have also moved the list of maintainers to a separate file.

I have kept all information intact (for now), with two exceptions:

• I removed duplicated information.
• For brevity's sake, I trimmed some explanations from the section about version checks.

I have restructured the CONTRIBUTING file to follow the order of the introductory "contribution process at a glance" section. This now serves as a bit of a table of contents.

There are still lots of improvements possible, fat to be trimmed, and sections to be moved to other documents, but I think this is a good basis for further improvement. I plan to continue working on these documents from time to time.

Closes: #5422

[srittau]

Possible further improvement:

• Add a section "setting up your environment" and move virtualenv stuff as well as pip install -r requirements there. Make that the second step.
• Move all the details about tests to a new file tests/README.md.

[srittau]

Also we should move black and isort instructions to their own section, linked from the ToC (in a followup PR).

[JelleZijlstra]

Thanks, looks great!

[srittau]

And another future PR: Move the code of conduct into a file CODE_OF_CONDUCT.md. This is specially treated by GitHub.

[Akuli]

I'm not sure if separate MAINTAINERS.md is a good idea. Will someone actually read it? When a maintainer talks, you can see it in the corner of the comment. A more useful thing would be to explain what a maintainer is when someone reading CONTRIBUTION.md sees it for the first time.

Also, we should say "maintainers" when we mean it. There used to be "core developers", and there still is an occurrence of "core team".

[Akuli]

Actually, the corner of a comment says "collaborator".

[JelleZijlstra]

Actually, the corner of a comment says "collaborator".

But I for some reason am a "member". I think that's an artifact of how we were added to the repo. We can still use "maintainer" in all internal documentation though.

[Akuli]

Actually, the corner of a comment says "collaborator". But I for some reason am a "member".

Perhaps this should be clarified when we start using "maintainer".

[srittau]

Separating maintainers has a few advantages, in my opinion:

• It's easy to find if you need the list. No more guessing whether it was in README or CONTRIBUTING.
• Making documents that are already too long shorter.
• Adding a maintainer doesn't trigger the "CONTRIBUTING has changed" warning when submitting a PR.

We could arguably add the list of maintainers to README, though, although I personally prefer to have it separate.

I will unify the wording to maintainer, though.

[srittau]

Jelle is a member of the Python organization, while Akuli and me are collaborators to this repository (but not members of the organization). "Maintainers" is a well established term, though.

[srittau]

Also, we have a few collaborators, who are not officially maintainers for reason I don't know. For example rchen.

[hauntsaninja]

I don't feel strongly about most of my comments, so ignore if you think things are fine / if you want to avoid scope creep and just want to move around existing text

[hauntsaninja]

Maybe we can more prominently mention a) where / how to ask for help, b) how to get started contributing (good-first-issue label / link to #4641 )

[srittau]

There is a section about where to get help in the README. That said, I'm sure this can be improved, but I'd suggest to move this to a separate PR.

[hauntsaninja]

Thanks for doing this! :-)