[gentoo-dev] [RFC] Reinstating old-school GLEPs masterplan

[Michał Górny]

Hi,

TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
than Wiki, put in a nice git repo.

Bug: https://bugs.gentoo.org/628098


A short bit of history
======================

A long time ago, in a gal... oh wait. Back in the old good days GLEPs
were reStructuredText files stored in our CVS repo (along with the GLEP
project page). The idea closely resembles the one used for PEPs
in Python. Similarly to the Python project, we had a docutils plugin to
convert GLEPs into 'nice' HTML, and so on, and so on.

Then there was the wiki boom, and GLEPs were wikified as part of that.
This brings us to where we are now.


Problems with wiki
==================

I've already listed them in detail [1]. The most relevant points, copied
from the bug [2]:

> 1. Lack of proper review platform and merge capability. We end up
> reinventing the wheel poorly by copying articles and requesting review
> of that. Then GLEP editors move them back eating history and sometimes
> resulting in even worse failures like including a temporary subpage in
> GLEP namespace [a]. Getting a GLEP in place sometimes takes GLEP
> editors over *a month* during which time there is not even a clear
> indication that a GLEP has update pending.
>
> 2. The wiki form does not really fit GLEPs. Note that RFCs are plain
> text files. PEPs use reStructuredText which is also pretty close to
> plain text. MediaWiki GLEPs are only mildly readable as plain text,
> and sometimes end up referring to external templates or other
> materials. They are not stand-alone, and they are hard to copy to use
> outside the wiki.
>
> 3. MediaWiki is not very good at accessibility. It's not convenient
> for anything more complex than quick article edits, and it ends up
> being real PITA for people with disabilities [b].
>
> [...]
> [a]:https://wiki.gentoo.org/wiki/GLEP:73/VerificationAlgo
> [b]:https://archives.gentoo.org/gentoo-project/message/01fc23841c98670b2419a8638f97ec0b


The target layout
=================

What I'd like to do is to restore the 'old school' file-based layout,
albeit in a bit more modern form. The idea is that GLEPs will be stored
as reStructuredText files in a dedicated git repository. The rendered
HTML versions will be available from our main site.

This simple solution will introduce a number of advantages:

a. the original source text of GLEPs will be once more readable,
and useful without the HTML rendering or external templates; for reviews
we wouldn't have to resort to a web browser,

b. everyone will be able to clone the GLEP repo and work on their
branches locally, then GLEP editors will be able to merge/cherry-pick
the changes to master without discarding history,

c. it will be possible to work on GLEPs without using a web browser or
having Internet access.


The masterplan
==============

The plan on introducing the changes follows:

1. Convert the old GLEP repository from CVS to git (done [3]),

2. Prepare www.g.o to render GLEPs (done [4]),

3. Convert the one GLEP that was written in GuideXML to reST,

4. Update GLEPs from wiki,

5. Update GLEP-1/2 for the new-old workflow,

6. Profit!

For steps 3 onwards I'd gladly accept some help. If someone wants to
help, please contact me and I'll help you get started. Otherwise, I will
just update them at my own pace, as time permits.


Any comments?

[1]:https://archives.gentoo.org/gentoo-project/message/bf6cdaeb6c9c689b32e1f0c55447ca5d
[2]:https://bugs.gentoo.org/628098
[3]:https://github.com/mgorny/glep-draft
[4]:https://github.com/mgorny/www-gentoo-org (gleps branch)

-- 
Best regards,
Michał Górny