Meta: document developer (and admin) workflows on GitHub and otherwise

[fingolfin]

We really should document far more things, for GAP developers (committers and non-committers) and also admins. This then is both useful for onboarding of new contributors; but also for existing developers, and admins. It'll make sure things can move on even if certain people with (currently) critical knowledge that nobody else has are not available.

At least three places come to mind for this kind of information:

1. CONTRIBUTING.md in the repository: available to everybody using GAP, also offline; but updating it requires some effort
2. One or multiple Wiki pages -- very easy to edit, but only available online
3. In one of the manuals.

Personally I'd use 1. for things that are not likely to change a lot, and 2. for the rest. E.g. CONTRIBUTING.md can contain general information about how we make releases; while the wiki would contain concrete dates for upcoming releases.

A list of information I think we should document:

• how the CI setup works (see Document CI setup (AppVeyor/Codecov/Travis) #907 and Target citests in Makefile? #1740)
• how releases are made: @alex-konovalov already created docs for that, see here, but not everybody knows about them, so I'd add link to them in a central location
• when releases are made (at some point we said we'd like to make a new major release every 6 month, and then 1-3 minor updates in between, depending on need); but see also issue Meta: Improve our release process #636
  • also list planned/expected dates for the next two or so major releases somewhere (e.g. Wiki)
• explain about GitHub labels, and how we mean to use them (see also issue Create checklist for PRs and issues #2721)
  • perhaps also give a rough overview of what labels there are, and what they are for?
  • also explain how this is critical for creating release notes
• explain about GitHub milestones, and how we mean to use them
• explain that nobody should commit directly to master, everything should go via PRs
• explain how backporting from master to stable branches works (including labels); see also issue Document how to mark commits on master for cherry picking to stable branch #2254
• explain that PRs are by default "rebased" (not merged or squashed)
• explain about rules for good commit messages
• GitHub admin:
  • whom do we give commit rights, and how? For that latter: by adding them to the GitHub group "GAP committer
  • to allow people to add labels, approve PRs and more, they can be added to the "GAP contributors" group (this does allow for pushing / merging of PRs)
  • explain how "GAP contributors" works: by giving members "Write" permission for gap-system/gap and gap-system/GapWWW (TODO: extend in the future), but then taking away right to commit (and to dismiss reviews) via GitHub's "branch protection rules)
• DNS records for gap-system.org : who can edit them?
• website: how to modify the website (pointer to GapWWW repository)
• mailing lists: how admins them?
• Slack: who is in charge / who can invite new people (everybody)...

For all of this, there is a tension between being comprehensive, and staying as terse as possible (so as to not overwhelm the reader, and increasing the likelihood that the notes will actually be read)

I am sure there are more things we should document. Please make suggestions below, I'll add them here as appropriate.

[ssiccha]

I'd like to keep the CONTRIBUTING.md focused on onboarding new contributors as it ATM mostly contains information on how to

• report issues,
• submit PRs,
• review PRs.

We could put all other information into the dev/ directory, and add an overview file DEVELOPERS.md. We can e.g. add a RELEASE-WORKFLOW.md to the dev/ directory.