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

[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

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

[Michael Orlitzky]

On 09/11/2017 01:08 PM, Michał Górny wrote:
> Hi,
> 
> TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
> than Wiki, put in a nice git repo.
> 

I generally agree with you that wiki markup is terrible and that a text
editor and a git repo is The Right Way to do things (with Jekyll or
whatever to push it to the web). But in my experience, crappy and easy
is a better way to get people to contribute. When I've taken wiki
documents and moved them into git repos, more often than not I become
the sole contributor, and otherwise-technical people just start emailing
me their contributions (which decrease greatly in frequency).

Will it be possible to build the GLEP rst files locally, and view the
output exactly as it would appear on the website? I ask because, so long
as you don't want to be able to preview the result, you can already
write MediaWiki markup into a text file locally. The offline "live
preview" ability is the killer feature of RST as I see it.

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

[Kristian Fiskerstrand]

[-- Attachment #1.1: Type: text/plain, Size: 977 bytes --]

On 09/11/2017 07:29 PM, Michael Orlitzky wrote:
> I generally agree with you that wiki markup is terrible and that a text
> editor and a git repo is The Right Way to do things (with Jekyll or
> whatever to push it to the web). But in my experience, crappy and easy
> is a better way to get people to contribute. 

I generally agree with this as well, but I don't like that we're
shifting back and forth as much as we do, which is a further hindrance.
At some point we just need to decide on something and go with it,
whether that is Wiki, RST or LaTeX..

The accessibility issues of wiki review and editing is a reasonable
argument, but we probably don't want to rush a change again.

Maybe we should start by defining a set of criteria / RFP for how we
would like the GLEP process to be and the format required?

-- 
Kristian Fiskerstrand
OpenPGP keyblock reachable at hkp://pool.sks-keyservers.net
fpr:94CB AFDD 3034 5109 5618 35AA 0B7F 8B60 E3ED FAE3


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Rich Freeman]

On Mon, Sep 11, 2017 at 10:29 AM, Michael Orlitzky <mjo@gentoo.org> wrote:
>
> But in my experience, crappy and easy
> is a better way to get people to contribute. When I've taken wiki
> documents and moved them into git repos, more often than not I become
> the sole contributor, and otherwise-technical people just start emailing
> me their contributions (which decrease greatly in frequency).
>

I'd tend to agree if people could actually edit stuff on the Wiki.
The problem is that there is really no way to do the equivalent of a
pull request or other review process on a Wiki.

Either we open pages up, in which case we have to watch them for
changes we don't want.  Or we don't open them up, in which case
suggesting patches is a royal pain.

I've wanted to propose more significant changes to the handbook and it
is hard to do because I can't just offer one big patch that people can
comment on.  I could start making little changes here and there but
until they're all done it will be inconsistent, and it makes it harder
to influence the overall direction.

-- 
Rich

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

[Robin H. Johnson]

[-- Attachment #1: Type: text/plain, Size: 1063 bytes --]

On Mon, Sep 11, 2017 at 01:29:38PM -0400, Michael Orlitzky wrote:
> Will it be possible to build the GLEP rst files locally, and view the
> output exactly as it would appear on the website? I ask because, so long
> as you don't want to be able to preview the result, you can already
> write MediaWiki markup into a text file locally. The offline "live
> preview" ability is the killer feature of RST as I see it.
Yes, this capability existed in the old CVS repo, along with the glep.py
tool that was part of dev-python/docutils.

'make' was sufficient to trigger the build. It would be nice to ensure
that the HTML build process was still easily accessible.

glep.py was a tiny wrapper for rst2html.py, which should be even easier
to get working now, since it can take arguments rather than needing
python overrides.

-- 
Robin Hugh Johnson
Gentoo Linux: Dev, Infra Lead, Foundation Asst. Treasurer
E-Mail   : robbat2@gentoo.org
GnuPG FP : 11ACBA4F 4778E3F6 E4EDF38E B27B944E 34884E85
GnuPG FP : 7D0B3CEB E9B85B1F 825BCECF EE05E6F6 A48F6136

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 1113 bytes --]

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

[Michał Górny]

W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael
Orlitzky napisał:
> On 09/11/2017 01:08 PM, Michał Górny wrote:
> > Hi,
> > 
> > TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
> > than Wiki, put in a nice git repo.
> > 
> 
> I generally agree with you that wiki markup is terrible and that a text
> editor and a git repo is The Right Way to do things (with Jekyll or
> whatever to push it to the web). But in my experience, crappy and easy
> is a better way to get people to contribute. When I've taken wiki
> documents and moved them into git repos, more often than not I become
> the sole contributor, and otherwise-technical people just start emailing
> me their contributions (which decrease greatly in frequency).

Rich already answered this in detail, so I'll skip it.

> Will it be possible to build the GLEP rst files locally, and view the
> output exactly as it would appear on the website? I ask because, so long
> as you don't want to be able to preview the result, you can already
> write MediaWiki markup into a text file locally. The offline "live
> preview" ability is the killer feature of RST as I see it.

Of course yes. However, the exactness of result depends on how much
effort you put into it.

The 'easy way' is rst2html.py (dev-python/docutils). It will give you
a rough rendering with a standard style, i.e. kinda ugly but enough to
see if everything works as expected. You'll also see the preamble as big
mumbo-jumbo on top.

Then, there's glep.py (dev-python/docutils-glep) which adds preamble
parsing, table of contents and some styling. AFAICS it needs a bit
handiwork (copying a stylesheet to a relative directory) but it gives
nice old-school rendering.

Then, you can just take www.gentoo.org and run it locally. It takes
a little more effort but jekyll is really trivial to set up and run
locally. Then you see it exactly how it's gonna look on g.o.

As a side note, we may also rename GLEPs to .rst. Then, GitHub will also
provide out-of-the-box rendering of them.

-- 
Best regards,
Michał Górny

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

[Michał Górny]

W dniu pon, 11.09.2017 o godzinie 22∶56 +0200, użytkownik Michał Górny
napisał:
> W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael
> Orlitzky napisał:
> > On 09/11/2017 01:08 PM, Michał Górny wrote:
> > > Hi,
> > > 
> > > TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
> > > than Wiki, put in a nice git repo.
> > > 
> > 
> > I generally agree with you that wiki markup is terrible and that a text
> > editor and a git repo is The Right Way to do things (with Jekyll or
> > whatever to push it to the web). But in my experience, crappy and easy
> > is a better way to get people to contribute. When I've taken wiki
> > documents and moved them into git repos, more often than not I become
> > the sole contributor, and otherwise-technical people just start emailing
> > me their contributions (which decrease greatly in frequency).
> 
> Rich already answered this in detail, so I'll skip it.
> 
> > Will it be possible to build the GLEP rst files locally, and view the
> > output exactly as it would appear on the website? I ask because, so long
> > as you don't want to be able to preview the result, you can already
> > write MediaWiki markup into a text file locally. The offline "live
> > preview" ability is the killer feature of RST as I see it.
> 
> Of course yes. However, the exactness of result depends on how much
> effort you put into it.
> 
> The 'easy way' is rst2html.py (dev-python/docutils). It will give you
> a rough rendering with a standard style, i.e. kinda ugly but enough to
> see if everything works as expected. You'll also see the preamble as big
> mumbo-jumbo on top.
> 
> Then, there's glep.py (dev-python/docutils-glep) which adds preamble
> parsing, table of contents and some styling. AFAICS it needs a bit
> handiwork (copying a stylesheet to a relative directory) but it gives
> nice old-school rendering.
> 
> Then, you can just take www.gentoo.org and run it locally. It takes
> a little more effort but jekyll is really trivial to set up and run
> locally. Then you see it exactly how it's gonna look on g.o.
> 
> As a side note, we may also rename GLEPs to .rst. Then, GitHub will also
> provide out-of-the-box rendering of them.
> 

Example of GitHub rendering:
https://github.com/mgorny/glep-draft/blob/preamble-test/glep-0001.rst

IMO this beats the preview/editing capabilities MediaWiki gave us.

-- 
Best regards,
Michał Górny

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

[Michael Orlitzky]

On 09/11/2017 05:06 PM, Michał Górny wrote:
> 
> Example of GitHub rendering:
> https://github.com/mgorny/glep-draft/blob/preamble-test/glep-0001.rst
> 
> IMO this beats the preview/editing capabilities MediaWiki gave us.
> 

If that's how we get an offline preview, I'm not sold =P

I can run MediaWiki locally too, and keep the source in a git repo. Your
other methods of getting a local preview don't sound significantly
easier than that -- at least, not enough so to justify throwing
everything out and starting all over again.

It looks like we're just treading water here, but I can live with it
either way.

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

[Michał Górny]

W dniu pon, 11.09.2017 o godzinie 17∶27 -0400, użytkownik Michael
Orlitzky napisał:
> On 09/11/2017 05:06 PM, Michał Górny wrote:
> > 
> > Example of GitHub rendering:
> > https://github.com/mgorny/glep-draft/blob/preamble-test/glep-0001.rst
> > 
> > IMO this beats the preview/editing capabilities MediaWiki gave us.
> > 
> 
> If that's how we get an offline preview, I'm not sold =P
> 
> I can run MediaWiki locally too, and keep the source in a git repo.

Can you set a MediaWiki instance with contents in less than 5 easy
steps? (easy = typing a reasonably short command, not 'set a mysql
server up')

>  Your
> other methods of getting a local preview don't sound significantly
> easier than that -- at least, not enough so to justify throwing
> everything out and starting all over again.

If you consider doing 'rst2html.py glep-0001.rst > glep-0001.html' hard,
then I'm afraid I won't be able to ever satisfy you.

-- 
Best regards,
Michał Górny

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

[Michael Orlitzky]

On 09/12/2017 09:50 AM, Michał Górny wrote:
> 
> If you consider doing 'rst2html.py glep-0001.rst > glep-0001.html' hard,
> then I'm afraid I won't be able to ever satisfy you.
> 

Does that command produce something that looks as good as this?

  https://wiki.gentoo.org/wiki/User:Mjo/GLEP:User_packages

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

[Michał Górny]

W dniu wto, 12.09.2017 o godzinie 09∶57 -0400, użytkownik Michael
Orlitzky napisał:
> On 09/12/2017 09:50 AM, Michał Górny wrote:
> > 
> > If you consider doing 'rst2html.py glep-0001.rst > glep-0001.html' hard,
> > then I'm afraid I won't be able to ever satisfy you.
> > 
> 
> Does that command produce something that looks as good as this?
> 
>   https://wiki.gentoo.org/wiki/User:Mjo/GLEP:User_packages
> 

No, it doesn't. However, you are free to prepare a stylesheet for
docutils that produces the rendering you like.

-- 
Best regards,
Michał Górny

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

[R0b0t1]

Hello friends,

On Mon, Sep 11, 2017 at 3:56 PM, Michał Górny <mgorny@gentoo.org> wrote:
> W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael
> Orlitzky napisał:
>> On 09/11/2017 01:08 PM, Michał Górny wrote:
>> > Hi,
>> >
>> > TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
>> > than Wiki, put in a nice git repo.
>> >
>>
>> I generally agree with you that wiki markup is terrible and that a text
>> editor and a git repo is The Right Way to do things (with Jekyll or
>> whatever to push it to the web). But in my experience, crappy and easy
>> is a better way to get people to contribute. When I've taken wiki
>> documents and moved them into git repos, more often than not I become
>> the sole contributor, and otherwise-technical people just start emailing
>> me their contributions (which decrease greatly in frequency).
>
> [...]
>
> Then, you can just take www.gentoo.org and run it locally. It takes
> a little more effort but jekyll is really trivial to set up and run
> locally. Then you see it exactly how it's gonna look on g.o.
>

I previously suggested Gollum and think I should suggest it again.
Gollum provides features relevant to a Wiki setting including web
editing. It would not require pages be rewritten and can render
MediaWiki that is maintained in a Git repository. It should be all of
the positives with no negatives.

Please refer to a statement by a project contributor and the original
author: https://github.com/gollum/gollum/issues/712.

Respectfully,
     R0b0t1

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

[Michał Górny]

W dniu pon, 11.09.2017 o godzinie 21∶59 -0500, użytkownik R0b0t1
napisał:
> Hello friends,
> 
> On Mon, Sep 11, 2017 at 3:56 PM, Michał Górny <mgorny@gentoo.org> wrote:
> > W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael
> > Orlitzky napisał:
> > > On 09/11/2017 01:08 PM, Michał Górny wrote:
> > > > Hi,
> > > > 
> > > > TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
> > > > than Wiki, put in a nice git repo.
> > > > 
> > > 
> > > I generally agree with you that wiki markup is terrible and that a text
> > > editor and a git repo is The Right Way to do things (with Jekyll or
> > > whatever to push it to the web). But in my experience, crappy and easy
> > > is a better way to get people to contribute. When I've taken wiki
> > > documents and moved them into git repos, more often than not I become
> > > the sole contributor, and otherwise-technical people just start emailing
> > > me their contributions (which decrease greatly in frequency).
> > 
> > [...]
> > 
> > Then, you can just take www.gentoo.org and run it locally. It takes
> > a little more effort but jekyll is really trivial to set up and run
> > locally. Then you see it exactly how it's gonna look on g.o.
> > 

I'm going to reply to the Gollum topic here since it's the first mail
according to date.

> I previously suggested Gollum and think I should suggest it again.
> Gollum provides features relevant to a Wiki setting including web
> editing.

Firstly, a generic request to everyone. If you want to suggest that we
are supposed to use your-favorite-tool instead of the one we have
deployed for a few years now, then please include:

1. A short summary including:

1a. How it fits into the desired workflow. Topics such as access control
and caching are of particular interest to me.

1b. What possible future use it could have.

1c. How much effort will the future maintenance take.

2. A publicly available working instance that resembles the workflow
we're aiming for, or an easy way of setting one up. Easy = ~5 simple
shell commands, not 'set a webserver up'.

3. A statement from an Infra member that is willing to set the instance
up and maintain it.

Because otherwise we're only going to lose time on theoretical debates
over software without even knowing if it will work at all, do what it's
supposed to do, and most importantly, if someone will actually set
a production instance up and maintain it afterwards.

Infra already maintains enough diverse platforms/services/frameworks
that serve only a single tool selected by one person who used to like
it, and not maintained anymore. SMW belongs to that group.

>  It would not require pages be rewritten and can render
> MediaWiki that is maintained in a Git repository.

Secondly, even if Gollum supported MW markup to the point of rendering
GLEPs (which it doesn't [1]), MW markup is not suitable for any
technical specifications or serious documentation for two reasons:

a. MW markup is not proper WYWIWYG. Any more complex part of
the document is not readable as plaintext. Add to that the horrible
syntax requiring <nowiki> use mixed with inline HTML...

b. MW markup is not standalone. Our GLEPs already started heavily
depending on random templates (which can change at any time, breaking
GLEPs in the process btw).

> It should be all of the positives with no negatives.

Is it?


[1]:https://help.github.com/articles/supported-mediawiki-formats/

-- 
Best regards,
Michał Górny

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

[R0b0t1]

Hello,

On Tue, Sep 12, 2017 at 9:04 AM, Michał Górny <mgorny@gentoo.org> wrote:
> W dniu pon, 11.09.2017 o godzinie 21∶59 -0500, użytkownik R0b0t1
> napisał:
>> Hello friends,
>>
>> On Mon, Sep 11, 2017 at 3:56 PM, Michał Górny <mgorny@gentoo.org> wrote:
>> > W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael
>> > Orlitzky napisał:
>> > > On 09/11/2017 01:08 PM, Michał Górny wrote:
>> > > > Hi,
>> > > >
>> > > > TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
>> > > > than Wiki, put in a nice git repo.
>> > > >
>> > >
>> > > I generally agree with you that wiki markup is terrible and that a text
>> > > editor and a git repo is The Right Way to do things (with Jekyll or
>> > > whatever to push it to the web). But in my experience, crappy and easy
>> > > is a better way to get people to contribute. When I've taken wiki
>> > > documents and moved them into git repos, more often than not I become
>> > > the sole contributor, and otherwise-technical people just start emailing
>> > > me their contributions (which decrease greatly in frequency).
>> >
>> > [...]
>> >
>> > Then, you can just take www.gentoo.org and run it locally. It takes
>> > a little more effort but jekyll is really trivial to set up and run
>> > locally. Then you see it exactly how it's gonna look on g.o.
>> >
>
> I'm going to reply to the Gollum topic here since it's the first mail
> according to date.
>

There is a thread in gentoo-dev where I proposed the Handbook be
maintained with Gollum. I apologize if it was not visible, but I was
trying to not make a nuisance of myself.

>> I previously suggested Gollum and think I should suggest it again.
>> Gollum provides features relevant to a Wiki setting including web
>> editing.
>
> Firstly, a generic request to everyone. If you want to suggest that we
> are supposed to use your-favorite-tool instead of the one we have
> deployed for a few years now, then please include:
>

I believe I addressed all of these. Please make suggestions on my
writing so I can make it more readable if you have the time.

If I suggest a project I think it reasonable to expect you to refer to
that project's README. Here is a link:
https://github.com/gollum/gollum/blob/master/README.md.

> 1. A short summary including:
>
> 1a. How it fits into the desired workflow. Topics such as access control
> and caching are of particular interest to me.
>

It manages a Wiki using a Git repository. Access control is managed
through the Git repository and has Git's limitations. When using
Gollum it seems like access control is best done by creating
repositories. The web editor seems to lack authentication.

Gollum may have issues with caching[1]. Gollum is deployed by GitHub,
but most GitHub project Wikis may be small.

> 1b. What possible future use it could have.
>

It could maintain all public facing documents.

> 1c. How much effort will the future maintenance take.
>

I do not see how it would take more maintenance time than Jekyll. It
may take less as it offers Wiki specific features.

> 2. A publicly available working instance that resembles the workflow
> we're aiming for, or an easy way of setting one up. Easy = ~5 simple
> shell commands, not 'set a webserver up'.
>

The README offers concise instructions for setting up a demonstration
instance and scaling up. Should that be hard to read, a video is
available (https://www.youtube.com/watch?v=EauxgxsLDC4).

> 3. A statement from an Infra member that is willing to set the instance
> up and maintain it.
>

It seems like it is your burden to interpret the suggestion and refer
it to the people who would be maintaining it. If you don't want to
then that is fine.

> Because otherwise we're only going to lose time on theoretical debates
> over software without even knowing if it will work at all, do what it's
> supposed to do, and most importantly, if someone will actually set
> a production instance up and maintain it afterwards.
>

It is not possible for me to know everything you would like addressed
in advance.

Most of the problems Gentoo faces are unique enough that I do not
think it is reasonable to expect a useful solution to exist. There
will always be problems.

> Infra already maintains enough diverse platforms/services/frameworks
> that serve only a single tool selected by one person who used to like
> it, and not maintained anymore. SMW belongs to that group.
>
>>  It would not require pages be rewritten and can render
>> MediaWiki that is maintained in a Git repository.
>
> Secondly, even if Gollum supported MW markup to the point of rendering
> GLEPs (which it doesn't [1]), MW markup is not suitable for any
> technical specifications or serious documentation for two reasons:
>
> a. MW markup is not proper WYWIWYG. Any more complex part of
> the document is not readable as plaintext. Add to that the horrible
> syntax requiring <nowiki> use mixed with inline HTML...
>
> b. MW markup is not standalone. Our GLEPs already started heavily
> depending on random templates (which can change at any time, breaking
> GLEPs in the process btw).
>

Yes, I suppose the lack of templates might make it unusable.

I never meant to defend MW. It just might have been possible to avoid
rewriting many of the pages until absolutely necessary.

>> It should be all of the positives with no negatives.
>
> Is it?
>

I don't know. You are the one with more information than me. I only
stated as much because it genuinely seems like it is; follow up on my
suggestion if it looks like it may initially be suitable.

Even large problems like the lack of real authentication do not really
make the situation any worse than it already is with controlled Wiki
pages. For more restricted pages it is likely irrelevant.

There was quite a bit of research involved in my original suggestion
of Gollum, however I didn't think to look at some of the points you
brought up. It looks like it might not be suitable. It also looks like
there may not be anything "suitable," really, though static website
generation may be the least intrusive.

Respectfully,
     R0b0t1


[1]: https://github.com/gollum/gollum/issues/1078

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

[Michał Górny]

W dniu sob, 16.09.2017 o godzinie 02∶51 -0500, użytkownik R0b0t1
napisał:
> Hello,
> 
> On Tue, Sep 12, 2017 at 9:04 AM, Michał Górny <mgorny@gentoo.org> wrote:
> > W dniu pon, 11.09.2017 o godzinie 21∶59 -0500, użytkownik R0b0t1
> > napisał:
> > > Hello friends,
> > > 
> > > On Mon, Sep 11, 2017 at 3:56 PM, Michał Górny <mgorny@gentoo.org> wrote:
> > > > W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael
> > > > Orlitzky napisał:
> > > > > On 09/11/2017 01:08 PM, Michał Górny wrote:
> > > > > > Hi,
> > > > > > 
> > > > > > TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
> > > > > > than Wiki, put in a nice git repo.
> > > > > > 
> > > > > 
> > > > > I generally agree with you that wiki markup is terrible and that a text
> > > > > editor and a git repo is The Right Way to do things (with Jekyll or
> > > > > whatever to push it to the web). But in my experience, crappy and easy
> > > > > is a better way to get people to contribute. When I've taken wiki
> > > > > documents and moved them into git repos, more often than not I become
> > > > > the sole contributor, and otherwise-technical people just start emailing
> > > > > me their contributions (which decrease greatly in frequency).
> > > > 
> > > > [...]
> > > > 
> > > > Then, you can just take www.gentoo.org and run it locally. It takes
> > > > a little more effort but jekyll is really trivial to set up and run
> > > > locally. Then you see it exactly how it's gonna look on g.o.
> > > > 
> > 
> > I'm going to reply to the Gollum topic here since it's the first mail
> > according to date.
> > 
> 
> There is a thread in gentoo-dev where I proposed the Handbook be
> maintained with Gollum. I apologize if it was not visible, but I was
> trying to not make a nuisance of myself.
> 
> > > I previously suggested Gollum and think I should suggest it again.
> > > Gollum provides features relevant to a Wiki setting including web
> > > editing.
> > 
> > Firstly, a generic request to everyone. If you want to suggest that we
> > are supposed to use your-favorite-tool instead of the one we have
> > deployed for a few years now, then please include:
> > 
> 
> I believe I addressed all of these. Please make suggestions on my
> writing so I can make it more readable if you have the time.
> 
> If I suggest a project I think it reasonable to expect you to refer to
> that project's README. Here is a link:
> https://github.com/gollum/gollum/blob/master/README.md.
> 
> > 1. A short summary including:
> > 
> > 1a. How it fits into the desired workflow. Topics such as access control
> > and caching are of particular interest to me.
> > 
> 
> It manages a Wiki using a Git repository. Access control is managed
> through the Git repository and has Git's limitations. When using
> Gollum it seems like access control is best done by creating
> repositories. The web editor seems to lack authentication.

That's what I suspected. So you're talking about deploying a wiki
without the basic feature of a wiki. IOW, once again deploying a tool
more complex than necessary, and working it around to make it work for
our purpose.

> Gollum may have issues with caching[1]. Gollum is deployed by GitHub,
> but most GitHub project Wikis may be small.

That's not an answer. Generating all GLEPs takes around 60 seconds right
now. With jekyll, that's done once. If gollum regenerates them
frequently, it's not a feasible solution.

> > 1b. What possible future use it could have.
> > 
> 
> It could maintain all public facing documents.
> 
> > 1c. How much effort will the future maintenance take.
> > 
> 
> I do not see how it would take more maintenance time than Jekyll. It
> may take less as it offers Wiki specific features.

There's a major difference between maintaining one tool we know, and two
tools (because obviously we won't dump Jekyll instantly), the second one
we don't know anything about.

> > 2. A publicly available working instance that resembles the workflow
> > we're aiming for, or an easy way of setting one up. Easy = ~5 simple
> > shell commands, not 'set a webserver up'.
> > 
> 
> The README offers concise instructions for setting up a demonstration
> instance and scaling up. Should that be hard to read, a video is
> available (https://www.youtube.com/watch?v=EauxgxsLDC4).

That's not what I'm asking for. If it's that easy, then set it up.
What I want is a 'one click' solution that can get me running it without
major changes to my system, without effort on my end and in, say, less
than 5 minutes.

-- 
Best regards,
Michał Górny

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

[Daniel Campbell]

[-- Attachment #1.1: Type: text/plain, Size: 4323 bytes --]

On 09/11/2017 01:56 PM, Michał Górny wrote:
> W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael
> Orlitzky napisał:
>> On 09/11/2017 01:08 PM, Michał Górny wrote:
>>> Hi,
>>>
>>> TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
>>> than Wiki, put in a nice git repo.
>>>
>>
>> I generally agree with you that wiki markup is terrible and that a text
>> editor and a git repo is The Right Way to do things (with Jekyll or
>> whatever to push it to the web). But in my experience, crappy and easy
>> is a better way to get people to contribute. When I've taken wiki
>> documents and moved them into git repos, more often than not I become
>> the sole contributor, and otherwise-technical people just start emailing
>> me their contributions (which decrease greatly in frequency).
> 
> Rich already answered this in detail, so I'll skip it.
> 
>> Will it be possible to build the GLEP rst files locally, and view the
>> output exactly as it would appear on the website? I ask because, so long
>> as you don't want to be able to preview the result, you can already
>> write MediaWiki markup into a text file locally. The offline "live
>> preview" ability is the killer feature of RST as I see it.
> 
> Of course yes. However, the exactness of result depends on how much
> effort you put into it.
> 
> The 'easy way' is rst2html.py (dev-python/docutils). It will give you
> a rough rendering with a standard style, i.e. kinda ugly but enough to
> see if everything works as expected. You'll also see the preamble as big
> mumbo-jumbo on top.
> 
> Then, there's glep.py (dev-python/docutils-glep) which adds preamble
> parsing, table of contents and some styling. AFAICS it needs a bit
> handiwork (copying a stylesheet to a relative directory) but it gives
> nice old-school rendering.
> 
> Then, you can just take www.gentoo.org and run it locally. It takes
> a little more effort but jekyll is really trivial to set up and run
> locally. Then you see it exactly how it's gonna look on g.o.
> 
> As a side note, we may also rename GLEPs to .rst. Then, GitHub will also
> provide out-of-the-box rendering of them.
> 
To preface, I really like the idea to do this in Git. Much as I
appreciate what the wiki team has done, collaboration isn't quite as
smooth on it and as another person mentioned, it's hard to get reviews,
so you get to choose to leave something in your userspace (I liked your
Drafts namespace idea, fwiw) or edit a page anyway and hope for the best.

That said... Is it wise to rely on Ruby (via Jekyll) for critical
reference documents, given how often minor version bumps in Ruby disrupt
its ecosystem? Do we really need the entire www.gentoo.org repository in
order to view and hack on GLEPs? I see little reason for GLEPs to not be
in their own repository, depending on something more stable than Jekyll
and Ruby. Given that the doc tools themselves are written in Python, it
makes more sense (imo) to leverage Gentoo's existing technical
investment in Python and use something like app-text/pelican, which is
equally, if not more capable than Jekyll and will not require pulling in
Ruby just to hack on and preview some text. Every Gentoo system comes
with Python unless you go off the beaten path and know what you're
doing, so that's a bonus, too.

Of course, this changes if we need some extremely advanced behavior. I'm
not sure how easy it is to build a Pelican plugin, but there's an entire
repo full of them. [1] Pelican also uses a Makefile you can hack on
(even multiple publishing targets), and supports GNU gettext for
translations.

Or is Jekyll chosen purely because the current website is built with it?
In that case, it at least makes sense despite the heavyweight dependencies.

If anyone's interested in seeing a mockup of a few GLEPs in Pelican, I
can get that started.

Whether or not the structure works on GitHub is orthogonal to the
decision. Still, put me down in favor of switching to Git. Thanks for
putting together the proposal.

[1]: https://github.com/getpelican/pelican-plugins
-- 
Daniel Campbell - Gentoo Developer, Trustee, Treasurer
OpenPGP Key: 0x1EA055D6 @ hkp://keys.gnupg.net
fpr: AE03 9064 AE00 053C 270C  1DE4 6F7A 9091 1EA0 55D6


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Michał Górny]

W dniu wto, 12.09.2017 o godzinie 00∶07 -0700, użytkownik Daniel
Campbell napisał:
> On 09/11/2017 01:56 PM, Michał Górny wrote:
> > W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael
> > Orlitzky napisał:
> > > On 09/11/2017 01:08 PM, Michał Górny wrote:
> > > > Hi,
> > > > 
> > > > TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
> > > > than Wiki, put in a nice git repo.
> > > > 
> > > 
> > > I generally agree with you that wiki markup is terrible and that a text
> > > editor and a git repo is The Right Way to do things (with Jekyll or
> > > whatever to push it to the web). But in my experience, crappy and easy
> > > is a better way to get people to contribute. When I've taken wiki
> > > documents and moved them into git repos, more often than not I become
> > > the sole contributor, and otherwise-technical people just start emailing
> > > me their contributions (which decrease greatly in frequency).
> > 
> > Rich already answered this in detail, so I'll skip it.
> > 
> > > Will it be possible to build the GLEP rst files locally, and view the
> > > output exactly as it would appear on the website? I ask because, so long
> > > as you don't want to be able to preview the result, you can already
> > > write MediaWiki markup into a text file locally. The offline "live
> > > preview" ability is the killer feature of RST as I see it.
> > 
> > Of course yes. However, the exactness of result depends on how much
> > effort you put into it.
> > 
> > The 'easy way' is rst2html.py (dev-python/docutils). It will give you
> > a rough rendering with a standard style, i.e. kinda ugly but enough to
> > see if everything works as expected. You'll also see the preamble as big
> > mumbo-jumbo on top.
> > 
> > Then, there's glep.py (dev-python/docutils-glep) which adds preamble
> > parsing, table of contents and some styling. AFAICS it needs a bit
> > handiwork (copying a stylesheet to a relative directory) but it gives
> > nice old-school rendering.
> > 
> > Then, you can just take www.gentoo.org and run it locally. It takes
> > a little more effort but jekyll is really trivial to set up and run
> > locally. Then you see it exactly how it's gonna look on g.o.
> > 
> > As a side note, we may also rename GLEPs to .rst. Then, GitHub will also
> > provide out-of-the-box rendering of them.
> > 
> 
> To preface, I really like the idea to do this in Git. Much as I
> appreciate what the wiki team has done, collaboration isn't quite as
> smooth on it and as another person mentioned, it's hard to get reviews,
> so you get to choose to leave something in your userspace (I liked your
> Drafts namespace idea, fwiw) or edit a page anyway and hope for the best.
> 
> That said... Is it wise to rely on Ruby (via Jekyll) for critical
> reference documents, given how often minor version bumps in Ruby disrupt
> its ecosystem?

The point of using ReST (i.e. an established markup) and git
(established VCS) is to avoid depending on any particular software to
get things working, and to make it easy to replace the guts
as necessary.

Jekyll is what infra uses at the moment, so I see no reason to reinvent
the wheel just to prove the point.

>  Do we really need the entire www.gentoo.org repository in
> order to view and hack on GLEPs?

No, you don't.

>  I see little reason for GLEPs to not be
> in their own repository, depending on something more stable than Jekyll
> and Ruby.

They are, and they don't depend on Ruby at all. In fact, you can view
them using a line printer if you like.

>  Given that the doc tools themselves are written in Python, it
> makes more sense (imo) to leverage Gentoo's existing technical
> investment in Python and use something like app-text/pelican, which is
> equally, if not more capable than Jekyll and will not require pulling in
> Ruby just to hack on and preview some text. Every Gentoo system comes
> with Python unless you go off the beaten path and know what you're
> doing, so that's a bonus, too.

See the first part of my reply to R0b0t1.

> Of course, this changes if we need some extremely advanced behavior. I'm
> not sure how easy it is to build a Pelican plugin, but there's an entire
> repo full of them. [1] Pelican also uses a Makefile you can hack on
> (even multiple publishing targets), and supports GNU gettext for
> translations.
> 
> Or is Jekyll chosen purely because the current website is built with it?
> In that case, it at least makes sense despite the heavyweight dependencies.

That's exactly the point. I'm sorry, I thought it was obvious from what
I have written.

> If anyone's interested in seeing a mockup of a few GLEPs in Pelican, I
> can get that started.

You sure can. However, I have serious doubts about the value of
establishing yet another framework for a single thing that nobody will
afterwards use or maintain. See SMW.

> 
> Whether or not the structure works on GitHub is orthogonal to the
> decision. Still, put me down in favor of switching to Git. Thanks for
> putting together the proposal.
> 
> [1]: https://github.com/getpelican/pelican-plugins

-- 
Best regards,
Michał Górny

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

[Dean Stephens]

On 09/11/17 13:08, Michał Górny wrote:
> Any comments?
> 
Instead of spreading documentation back out across multiple sites and
changing workflow for a subset of it yet again, why not migrate the wiki
to e.g. gollum [1]? Given that it supports markdown, ReStructuredText,
and mediawiki markup and uses git for a backend.

[1] https://github.com/gollum/gollum

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

[Michał Górny]

W dniu pon, 11.09.2017 o godzinie 23∶26 -0400, użytkownik Dean Stephens
napisał:
> On 09/11/17 13:08, Michał Górny wrote:
> > Any comments?
> > 
> 
> Instead of spreading documentation back out across multiple sites and
> changing workflow for a subset of it yet again, why not migrate the wiki
> to e.g. gollum [1]? Given that it supports markdown, ReStructuredText,
> and mediawiki markup and uses git for a backend.
> 
> [1] https://github.com/gollum/gollum
> 

This seems to be entirely covered by an earlier post by R0b0t1, so
please read my reply to that post.

-- 
Best regards,
Michał Górny

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

[Michał Górny]

W dniu pon, 11.09.2017 o godzinie 19∶08 +0200, użytkownik Michał Górny
napisał:
> 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,

Update: those two points are done now, and open for comments/review
on 'wiki-updates' branch. There's a PR for convenience [1], and Council
confirmation request [2].

[1]:https://github.com/mgorny/glep-draft/pull/1
[2]:https://bugs.gentoo.org/630882

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