Open fingolfin opened 5 years ago
I'd like to keep the CONTRIBUTING.md
focused on onboarding new contributors as it ATM mostly contains information on how to
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.
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:
CONTRIBUTING.md
in the repository: available to everybody using GAP, also offline; but updating it requires some effortPersonally 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:
gap-system/gap
andgap-system/GapWWW
(TODO: extend in the future), but then taking away right to commit (and to dismiss reviews) via GitHub's "branch protection rules)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.