gap-system / gap

Main development repository for GAP - Groups, Algorithms, Programming, a System for Computational Discrete Algebra
https://www.gap-system.org
GNU General Public License v2.0
815 stars 161 forks source link

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

Open fingolfin opened 5 years ago

fingolfin commented 5 years ago

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:

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 commented 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.