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
