[gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Michał Górny]

Hi, everyone.

Following the backporting of all GLEP changes from the wiki to my draft
repository [1] (which is still open for a separate review), I have
prepared an update for GLEP 1 & 2. For your convenience, the update
is both sent as git patches in reply to this mail, and provided
as a GH pull request [2].

The notable changes are:

1. A new git-based workflow is introduced that is a combination
   of the old CVS workflow and the MW workflow (wrt access
   restrictions). The developers create branches or fork the GLEP
   repository, and work on their drafts there. GLEP editors merge
   changes into master to make them official.

2. The old ReST markup is restored. Previously, GLEPs allowed also
   GuideXML but this is not supported anymore.

3. The complete set of GLEP headers is restored, and they are updated
   for the modern workflow:

   - Last-Updated needs to be set manually,
   - Version is updated manually and is semantic,
   - all dates use ISO 8601 (GLEP 45).

4. Two minor changes are made for better interoperability (i.e. less
   custom code and better support for external tools):

   - source files are renamed from .txt to .rst,
   - headers are surrounded by '---' to be compatible with YAML Front
     Matter.

5. GLEP workflow is updated to account for additional statuses in use:

   - 'Withdrawn' when author withdraws the GLEP (used in 4 GLEPs),
   - 'Moribund' when GLEP is obsoleted without a replacement
     (historically used in 1 GLEP but the need was discussed recently).

Please review and comment.

[1]:https://github.com/gentoo/glep-draft/pull/1
[2]:https://github.com/gentoo/glep-draft/pull/2

--
Best regards,
Michał Górny

[gentoo-project] [PATCH 01/18] glep-0001: Update for the git workflow

[Michał Górny]

---
 glep-0001.txt | 42 ++++++++++++++++++++----------------------
 1 file changed, 20 insertions(+), 22 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 67bfd0c..452d5ba 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -32,9 +32,11 @@ documenting the design decisions that have gone into Gentoo Linux.  The GLEP
 author is responsible for building consensus within the community and
 documenting dissenting opinions.
 
-Because the GLEPs are maintained as Wiki pages, their edit history is
-publicly viewable. For the older GLEPs which started out in CVS, their
-revision history is the historical record of the feature proposal [#CVS]_.
+Because the GLEPs are maintained as text files in a VCS, their revision
+history is the historical record of the feature proposal [#VCS]_. For older
+GLEPs, the base repository may provide an approximate history of the changes.
+The original changes can still be found in [#CVS]_ for changes up to June 2013
+and/or [#WIKI]_ for changes onwards up to September 2017.
 
 
 Kinds of GLEPs
@@ -69,14 +71,15 @@ injected into the Gentoo Linux development work flow with an enhancement "bug"
 submitted to the Gentoo Linux bugzilla [#BUGS]_.
 
 The GLEP champion then files a bug on Bugzilla in the GLEP product, under
-the "New GLEP submissions" component of the "Documentation" product with
-a proposed title and a rough, but fleshed out, draft of the GLEP.  This
+the "New GLEP submissions" component of the "Documentation" product
+and prepares a rough, but fleshed out, draft of the GLEP on a dedicated
+branch of the GLEP repository or a private fork of that repository.  This
 draft must be written in GLEP style as described below and in GLEP 2.
 
 If the GLEP editors accept the GLEP, they will assign the GLEP a number, label
 it as Standards Track (a better name would be nice here -- suggestions?) or
-Informational, give it status "Draft", and create and check-in the initial
-draft of the GLEP on the Wiki in the GLEP namespace.  The GLEP editors will
+Informational, give it status "Draft", and merge the initial draft of the GLEP
+to the master branch of the repository.  The GLEP editors will
 not unreasonably deny a GLEP. Reasons for denying GLEP status include
 duplication of effort, being technically unsound, not providing proper
 motivation or addressing backwards compatibility, or not in keeping with
@@ -92,7 +95,7 @@ The author of the GLEP is then responsible for posting the GLEP to
 the gentoo-dev or gentoo-project mailing list (and additionally to
 the Gentoo Linux forums [#FORUMS]_ if they so desire), and marshaling community
 support for it.  As updates are necessary, the GLEP author should request
-changes to the Wiki page from a GLEP editor.
+merging changes to the master branch from a GLEP editor.
 
 Standards Track GLEPs consist of two parts, a design document and a reference
 implementation.  The GLEP should be reviewed and accepted before a reference
@@ -200,7 +203,7 @@ Each GLEP should have the following parts:
 8. Copyright -- Every new GLEP must be explicitly labelled
    as licensed under the Creative Commons Attribution-ShareAlike (CC-BY-SA)
    license, version 3.0 [#CC-BY-SA3.0]_. Older GLEPs in the public domain
-   should be relicensed to CC-BY-SA 3.0 when they are moved to the Wiki.
+   should be relicensed to CC-BY-SA 3.0 when they are updated.
    GLEPs released under the Open Publication License (OPL) may remain
    as-is, but are strongly encouraged to be relicensed under CC-BY-SA
    3.0 with the consent of all authors.
@@ -258,11 +261,6 @@ A GLEP may have a Replaces header, which indicates that this GLEP supersedes
 a previous one.  This header should contain the number of the GLEP that this
 one renders obsolete.
 
-When the GLEP editor enters the GLEP into the Wiki, they will be automatically
-prompted for the contents of these fields, which will then be associated with
-the GLEP as metadata.  The version of the GLEP stored on the Wiki should
-not contain the RFC 2822 headers as part of the body of the GLEP.
-
 
 Reporting GLEP Bugs, or Submitting GLEP Updates
 ===============================================
@@ -278,13 +276,13 @@ lost. Be sure to CC the GLEP author on the bug. When in doubt about where
 to send your changes, please check first with the GLEP author and/or GLEP
 editors.
 
-GLEP authors must have a GLEP editor commit their changes to the Wiki,
-as the GLEP namespace is restricted to GLEP editors in order to protect
+GLEP authors must have a GLEP editor merge their changes to the master branch,
+as the write access is restricted to GLEP editors in order to protect
 the integrity of the GLEPs.
 
 Any major updates to GLEPs (that is, those that change the content of
 the GLEP rather than just fixing typos or adding small clarifications)
-should be approved by the Gentoo Council before being committed.
+should be approved by the Gentoo Council before being merged.
 
 
 Transferring GLEP Ownership
@@ -316,11 +314,11 @@ References and Footnotes
 
 .. [#PEP1] http://www.python.org/peps/pep-0001.html
 
-.. [#CVS] This historical record is available by the normal CVS commands
-   for retrieving older revisions.  For those without direct access to the CVS
-   tree, you can browse the current and past GLEP revisions via the Gentoo
-   Linux viewcvs web site at
-   http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo/xml/htdocs/proj/en/glep/
+.. [#VCS] https://gitweb.gentoo.org/proj/glep.git
+
+.. [#CVS] https://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo/xml/htdocs/proj/en/glep/
+
+.. [#WIKI] https://wiki.gentoo.org/index.php?title=Special%3AAllPages&from=&to=&namespace=550
 
 .. [#BUGS] http://bugs.gentoo.org
 
-- 
2.14.1

[gentoo-project] [PATCH 02/18] glep-0001: Revert back to ReST markup

[Michał Górny]

---
 glep-0001.txt | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 452d5ba..257fd02 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -212,10 +212,11 @@ Each GLEP should have the following parts:
 GLEP Formating and Template
 ===========================
 
-GLEPs are written in Wiki markup [#wikimarkup]_, which is a markup language
-compatible with MediaWiki.  This format is both human-readable and displays
-well on the Gentoo Wiki.  GLEP 2 contains a boilerplate template [#GLEP2]_
-for use with Wiki markup GLEPs.
+GLEPs are written in ReStructuredText markup [#ReSTHOME]_ that is then
+converted to HTML using Docutils [#DOCUTILS]_.  Using ReStructuredText GLEPs
+allows for rich markup that is still quite easy to read, but results in much
+better-looking and more functional HTML.  GLEP 2 contains a boilerplate
+template [#GLEP2]_ for use with ReStructuredText GLEPs.
 
 
 GLEP Header
@@ -328,7 +329,9 @@ References and Footnotes
 
 .. [#CC-BY-SA3.0] http://creativecommons.org/licenses/by-sa/3.0/us/
 
-.. [#wikimarkup] http://en.wikipedia.org/wiki/Help:Wiki_markup
+.. [#ReSTHOME] http://docutils.sourceforge.net/rst.html
+
+.. [#DOCUTILS] http://docutils.sourceforge.net/
 
 .. [#GLEP2] http://glep.gentoo.org/glep-0002.html
 
-- 
2.14.1

[gentoo-project] [PATCH 03/18] glep-0001: Restore most of old GLEP headers

[Michał Górny]

Remove most of the headers that were lost while migrating the GLEPs
to Wiki, with the exception of Discussions-To that seems to have
no value for the GLEP workflow. Some of the headers will be subject
to refactoring the commits following.
---
 glep-0001.txt | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 257fd02..75bed31 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -228,13 +228,19 @@ header preamble.  The headers must appear in the following order.  Headers
 marked with "*" are optional. All other headers are required. ::
 
     GLEP: <glep number>
+    Version: <cvs version string>
+    Last-Modified: <cvs date string>
     Title: <glep title>
     Author: <list of authors' real names and optionally, email addrs>
     Status: <Draft | Active | Accepted | Deferred | Rejected |
              Final | Replaced>
     Type: <Informational | Standards Track>
+  * Content-Type: <text/x-rst>
+    Created: <date created on, in dd-mmm-yyyy format>
+    Post-History: <dates of postings to mailing lists>
   * Requires: <glep numbers>
   * Replaces: <glep number>
+  * Replaced-By: <glep number>
 
 The Author header lists the names, and optionally the email addresses
 of all the authors/owners of the GLEP.  Anybody who submits changes to
@@ -255,12 +261,21 @@ following RFC 2822 continuation line conventions.
 The Type header specifies the type of GLEP: Informational or Standards
 Track.
 
+The format of a GLEP is specified with a Content-Type header, which
+must be "text/x-rst" for ReStructuredText GLEPs (see GLEP 2 [#GLEP2]_).
+
+The Created header records the date that the GLEP was assigned a number, while
+Post-History is used to record the dates of when new versions of the GLEP are
+posted to gentoo-dev.  Both headers should be in dd-mmm-yyyy format, e.g.
+14-Aug-2001.
+
 GLEPs may have a Requires header, indicating the GLEP numbers that this GLEP
 depends on.
 
-A GLEP may have a Replaces header, which indicates that this GLEP supersedes
-a previous one.  This header should contain the number of the GLEP that this
-one renders obsolete.
+GLEPs may also have a Replaced-By header indicating that a GLEP has been
+rendered obsolete by a later document; the value is the number of the GLEP
+that replaces the current document.  The newer GLEP must have a Replaces
+header containing the number of the GLEP that it rendered obsolete.
 
 
 Reporting GLEP Bugs, or Submitting GLEP Updates
-- 
2.14.1

[gentoo-project] [PATCH 04/18] glep-0001: Reform Last-Updated to be updated manually

[Michał Górny]

Since we no longer use CVS, the Last-Updated header is not updated
automatically anymore. Update the GLEP to require manually updating it
whenever the changes are merged to master.
---
 glep-0001.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 75bed31..0a69824 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -229,7 +229,7 @@ marked with "*" are optional. All other headers are required. ::
 
     GLEP: <glep number>
     Version: <cvs version string>
-    Last-Modified: <cvs date string>
+    Last-Modified: <date of last update>
     Title: <glep title>
     Author: <list of authors' real names and optionally, email addrs>
     Status: <Draft | Active | Accepted | Deferred | Rejected |
@@ -264,9 +264,11 @@ Track.
 The format of a GLEP is specified with a Content-Type header, which
 must be "text/x-rst" for ReStructuredText GLEPs (see GLEP 2 [#GLEP2]_).
 
+The Last-Modified header specifies the date that the GLEP was last updated
+in the master branch.
 The Created header records the date that the GLEP was assigned a number, while
 Post-History is used to record the dates of when new versions of the GLEP are
-posted to gentoo-dev.  Both headers should be in dd-mmm-yyyy format, e.g.
+posted to gentoo-dev.  All three headers should be in dd-mmm-yyyy format, e.g.
 14-Aug-2001.
 
 GLEPs may have a Requires header, indicating the GLEP numbers that this GLEP
-- 
2.14.1

[gentoo-project] [PATCH 05/18] glep-0001: Provide a meaningful versioning for GLEPs

[Michał Górny]

---
 glep-0001.txt | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 0a69824..5d21609 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -228,7 +228,7 @@ header preamble.  The headers must appear in the following order.  Headers
 marked with "*" are optional. All other headers are required. ::
 
     GLEP: <glep number>
-    Version: <cvs version string>
+    Version: <major>[.<minor>]
     Last-Modified: <date of last update>
     Title: <glep title>
     Author: <list of authors' real names and optionally, email addrs>
@@ -242,6 +242,17 @@ marked with "*" are optional. All other headers are required. ::
   * Replaces: <glep number>
   * Replaced-By: <glep number>
 
+The Version field specifies the current version of the GLEP. The Version
+consists of a major version, optionally followed by a minor version (if
+non-zero). Every GLEP starts at version 1 which is successively incremented
+as changes are merged to the GLEP.
+
+The major version number should be incremented (and minor reset to zero)
+whenever the meaning of the GLEP changes. The minor version number should
+be incremented for changes that do not affect the basic meaning (e.g.
+clarifications, reference implementation updates). Editorial changes should
+be merged without increasing the version.
+
 The Author header lists the names, and optionally the email addresses
 of all the authors/owners of the GLEP.  Anybody who submits changes to
 the GLEP should be added to this field.The format of the Author header
-- 
2.14.1

[gentoo-project] [PATCH 06/18] glep-0001: Clarify the process on updating Replaced-By

[Michał Górny]

Indicate that the GLEPs should not be replaced until the replacement
GLEP is accepted.
---
 glep-0001.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 5d21609..64bdcaa 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -285,10 +285,10 @@ posted to gentoo-dev.  All three headers should be in dd-mmm-yyyy format, e.g.
 GLEPs may have a Requires header, indicating the GLEP numbers that this GLEP
 depends on.
 
-GLEPs may also have a Replaced-By header indicating that a GLEP has been
-rendered obsolete by a later document; the value is the number of the GLEP
-that replaces the current document.  The newer GLEP must have a Replaces
-header containing the number of the GLEP that it rendered obsolete.
+GLEPs may also have a Replaces header indicating that a GLEP is meant
+to replace one or more older GLEPs.  Once such a GLEP is accepted, a matching
+Replaced-By should be added to all replaced GLEPs and their status should
+be updated to Replaced.
 
 
 Reporting GLEP Bugs, or Submitting GLEP Updates
-- 
2.14.1

[gentoo-project] [PATCH 07/18] glep-0001: Replace dates with ISO 8601

[Michał Górny]

This has been proposed already as GLEP 45 but never merged. If it is
approved, we should mark GLEP 45 appropriately.
---
 glep-0001.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 64bdcaa..d048f4f 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -236,7 +236,7 @@ marked with "*" are optional. All other headers are required. ::
              Final | Replaced>
     Type: <Informational | Standards Track>
   * Content-Type: <text/x-rst>
-    Created: <date created on, in dd-mmm-yyyy format>
+    Created: <date created on>
     Post-History: <dates of postings to mailing lists>
   * Requires: <glep numbers>
   * Replaces: <glep number>
@@ -279,8 +279,8 @@ The Last-Modified header specifies the date that the GLEP was last updated
 in the master branch.
 The Created header records the date that the GLEP was assigned a number, while
 Post-History is used to record the dates of when new versions of the GLEP are
-posted to gentoo-dev.  All three headers should be in dd-mmm-yyyy format, e.g.
-14-Aug-2001.
+posted to gentoo-dev.  All three headers should be in ISO 8601 ``yyyy-mm-dd``
+format, e.g. 2001-08-14.
 
 GLEPs may have a Requires header, indicating the GLEP numbers that this GLEP
 depends on.
-- 
2.14.1

[gentoo-project] [PATCH 08/18] glep-0001: Require .rst suffix for interoperability

[Michał Górny]

---
 glep-0001.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/glep-0001.txt b/glep-0001.txt
index d048f4f..cb97033 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -218,6 +218,9 @@ allows for rich markup that is still quite easy to read, but results in much
 better-looking and more functional HTML.  GLEP 2 contains a boilerplate
 template [#GLEP2]_ for use with ReStructuredText GLEPs.
 
+For best interoperability, the GLEPs using ReStructuredText format must use
+``.rst`` file suffix.
+
 
 GLEP Header
 ===========
-- 
2.14.1

[gentoo-project] [PATCH 09/18] glep-0001: Require --- around preamble for interoperability

[Michał Górny]

---
 glep-0001.txt | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index cb97033..f72b228 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -227,9 +227,13 @@ GLEP Header
 
 Every GLEP has certain attributes associated with it. When a GLEP is sent
 to the mailing lists for discussion, it should begin with an RFC 2822 style
-header preamble.  The headers must appear in the following order.  Headers
-marked with "*" are optional. All other headers are required. ::
+header preamble between two triple-dashed lines.  The headers must appear
+in the following order.  Headers marked with "*" are optional. All other
+headers are required.
 
+::
+
+    ---
     GLEP: <glep number>
     Version: <major>[.<minor>]
     Last-Modified: <date of last update>
@@ -244,6 +248,7 @@ marked with "*" are optional. All other headers are required. ::
   * Requires: <glep numbers>
   * Replaces: <glep number>
   * Replaced-By: <glep number>
+    ---
 
 The Version field specifies the current version of the GLEP. The Version
 consists of a major version, optionally followed by a minor version (if
-- 
2.14.1

[gentoo-project] [PATCH 10/18] glep-0001: Add 'Withdrawn' status to workflow

[Michał Górny]

Include a 'Withdrawn' status in the workflow for explicit withdrawal
from the author. This status is currently used in four GLEPs: 19, 29,
51, 52.
---
 glep-0001.txt | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index f72b228..703d79f 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -135,6 +135,9 @@ A GLEP can also be assigned status "Deferred".  The GLEP author or editor can
 assign the GLEP this status when no progress is being made on the GLEP.  Once
 a GLEP is deferred, the GLEP editor can re-assign it to draft status.
 
+A GLEP can also be "Withdrawn" by the author.  A withdrawn GLEP can be taken
+over by another champion.
+
 A GLEP can also be "Rejected".  Perhaps after all is said and done it was not
 a good idea.  It is still important to have a record of this fact.
 
@@ -146,6 +149,8 @@ GLEP work flow is as follows::
     Draft -> Accepted -> Final -> Replaced
       ^
       +----> Rejected
+      |
+      +----> Withdrawn
       v
     Deferred
 
@@ -239,7 +244,7 @@ headers are required.
     Last-Modified: <date of last update>
     Title: <glep title>
     Author: <list of authors' real names and optionally, email addrs>
-    Status: <Draft | Active | Accepted | Deferred | Rejected |
+    Status: <Draft | Active | Accepted | Deferred | Withdrawn | Rejected |
              Final | Replaced>
     Type: <Informational | Standards Track>
   * Content-Type: <text/x-rst>
-- 
2.14.1

[gentoo-project] [PATCH 11/18] glep-0001: Add a "Moribund" status for obsolete GLEPs

[Michał Górny]

Add an explicit "Moribund" status that can be used to obsolete GLEPs
without giving an explicit replacement. This status was historically
used in GLEP 33 before it was migrated to Wiki.
---
 glep-0001.txt | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 703d79f..3ad2b39 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -144,11 +144,14 @@ a good idea.  It is still important to have a record of this fact.
 GLEPs can also be replaced by a different GLEP, rendering the original
 obsolete (where version 2 of a policy, for example, might replace version 1).
 
+If a "Final" GLEP becomes obsolete and requires no explicit replacement,
+it can be marked "Moribund".
+
 GLEP work flow is as follows::
 
     Draft -> Accepted -> Final -> Replaced
-      ^
-      +----> Rejected
+      ^                    |
+      +----> Rejected      +----> Moribund
       |
       +----> Withdrawn
       v
@@ -245,7 +248,7 @@ headers are required.
     Title: <glep title>
     Author: <list of authors' real names and optionally, email addrs>
     Status: <Draft | Active | Accepted | Deferred | Withdrawn | Rejected |
-             Final | Replaced>
+             Final | Replaced | Moribund>
     Type: <Informational | Standards Track>
   * Content-Type: <text/x-rst>
     Created: <date created on>
-- 
2.14.1

[gentoo-project] [PATCH 12/18] glep-0001: Sync the RFC no to 2822 between sections

[Michał Górny]

---
 glep-0001.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 3ad2b39..65bc37a 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -166,7 +166,7 @@ What belongs in a successful GLEP?
 
 Each GLEP should have the following parts:
 
-1. Preamble -- RFC 822 style headers containing meta-data about the
+1. Preamble -- RFC 2822 style headers containing meta-data about the
    GLEP, including the GLEP number, a short descriptive title (limited
    to a maximum of 44 characters), the names, and optionally the
    contact info for each author, etc.
-- 
2.14.1

[gentoo-project] [PATCH 13/18] glep-0001: Do not require a specific header order

[Michał Górny]

Most of the GLEPs never really followed the header order specified
in GLEP 1, and there is no technical reason to enforce that.
---
 glep-0001.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 65bc37a..22787bf 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -235,9 +235,8 @@ GLEP Header
 
 Every GLEP has certain attributes associated with it. When a GLEP is sent
 to the mailing lists for discussion, it should begin with an RFC 2822 style
-header preamble between two triple-dashed lines.  The headers must appear
-in the following order.  Headers marked with "*" are optional. All other
-headers are required.
+header preamble between two triple-dashed lines.  Headers marked with "*" are
+optional. All other headers are required.
 
 ::
 
-- 
2.14.1

[gentoo-project] [PATCH 14/18] glep-0001: Make Content-Type obligatory

[Michał Górny]

The GLEP does not specify the exact behavior for handling GLEPs without
a Content-Type, and it might be subject to historical weirdnesses, so
just require it unconditionally.
---
 glep-0001.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 22787bf..8b8adf2 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -249,7 +249,7 @@ optional. All other headers are required.
     Status: <Draft | Active | Accepted | Deferred | Withdrawn | Rejected |
              Final | Replaced | Moribund>
     Type: <Informational | Standards Track>
-  * Content-Type: <text/x-rst>
+    Content-Type: <text/x-rst>
     Created: <date created on>
     Post-History: <dates of postings to mailing lists>
   * Requires: <glep numbers>
-- 
2.14.1

[gentoo-project] [PATCH 15/18] glep-0001: Add myself as co-author

[Michał Górny]

---
 glep-0001.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 8b8adf2..2112d41 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -2,7 +2,8 @@ GLEP: 1
 Title: GLEP Purpose and Guidelines
 Version: $Revision$
 Last-Modified: $Date$
-Author: Grant Goodyear <g2boojum@gentoo.org>
+Author: Grant Goodyear <g2boojum@gentoo.org>,
+        Michał Górny <mgorny@gentoo.org>
 Status: Active
 Type: Informational
 Content-Type: text/x-rst
-- 
2.14.1

[gentoo-project] [PATCH 16/18] glep-0002: Revert to ReST version

[Michał Górny]

---
 glep-0002.txt | 602 +++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 468 insertions(+), 134 deletions(-)

diff --git a/glep-0002.txt b/glep-0002.txt
index 0d3aec7..06a1964 100644
--- a/glep-0002.txt
+++ b/glep-0002.txt
@@ -1,172 +1,358 @@
 GLEP: 2
-Title: Sample Wiki Markup GLEP Template
+Title: Sample ReStructuredText GLEP Template
 Version: $Revision$
 Last-Modified: $Date$
-Author:	Grant Goodyear <g2boojum@gentoo.org>, Chris Reffett <creffett@gentoo.org>
+Author:	Grant Goodyear <g2boojum@gentoo.org>,
 Status: Active
 Type: Informational
-Content-Type: text/x-wiki
+Content-Type: text/x-rst
 Created: 31 May 2003
 Post-History: 2-Jun-2003, 17-Dec-2013
 
-==Credits==
 
-The text of this GLEP was, to a significant extent, stolen from Python's <ref name="python">http://www.python.org</ref> PEP-0012 <ref name="pep12"> http://www.python.org/peps/pep-0012.html</ref> by David Goodger and Barry A. Warsaw.
+Credits
+=======
 
-Note: if you are reading this GLEP via the web, you should first grab the text (Wiki Markup) source of this GLEP in order to complete the steps below.  '''DO NOT USE THE HTML FILE AS YOUR TEMPLATE!'''
+The text of this GLEP was, to a significant extent, stolen from Python's
+[#PYTHON]_ PEP-0012 [#PEP12]_ by David Goodger and Barry A. Warsaw.
 
-To get the source of this (or any) GLEP, look at the top of the page and click on the link titled "View source".
 
-==Abstract==
+Abstract
+========
 
-This GLEP provides a boilerplate or sample template for creating your own Wiki text GLEPs.  In conjunction with the content guidelines in GLEP 1 <ref name="glep1">GLEP 1, GLEP Purpose and Guidelines, Goodyear, (http://wiki.gentoo.org/index.php?title=GLEP:1)</ref>, this should make it easy for you to conform your own GLEPs to the format outlined below.                                                                                                                                                                          
+This GLEP provides a boilerplate or sample template for creating your own
+reStructuredText GLEPs.  In conjunction with the content guidelines in GLEP 1
+[#GLEP1]_, this should make it easy for you to conform your own GLEPs to the
+format outlined below.
 
-==Motivation==                                   
+Note: if you are reading this GLEP via the web, you should first grab the text
+(reStructuredText) source of this GLEP in order to complete the steps below.
+**DO NOT USE THE HTML FILE AS YOUR TEMPLATE!**
 
-Provide adequate motivation here.  In this particular case, we need to provide people with the information necessary to submit GLEPs in the proper form.                                                                                                                                                        
+To get the source of this (or any) GLEP, look at the top of the HTML page and
+click on the link titled "GLEP Source".
 
-==Rationale==
+Motivation
+==========
 
-GLEP submissions come in a wide variety of forms, not all adhering to the format guidelines set forth below.  Use this template, in conjunction with the format guidelines below, to ensure that your GLEP submission won't get automatically rejected because of form.                                                                                                                                                                                          
+Provide adequate motivation here.  In this particular case, we need to provide
+people with the information necessary to submit GLEPs in the proper form.
 
-Wiki Markup is used to allow GLEP authors more functionality and expressivity, while maintaining easy readability in the source text.  The format makes the functionality accessible to readers: live hyperlinks, styled text, tables, images, and automatic tables of contents, among other advantages.  
+Rationale
+=========
 
-==Backwards Compatibility==
+GLEP submissions come in a wide variety of forms, not all adhering to the
+format guidelines set forth below.  Use this template, in conjunction with the
+format guidelines below, to ensure that your GLEP submission won't get
+automatically rejected because of form.
 
-Not a problem for this GLEP.  This section should be included even when it is only to state that there are no backwards compatibility issues.
+ReStructuredText is used to allow GLEP authors more functionality and
+expressivity, while maintaining easy readability in the source text.  The
+processed HTML form makes the functionality accessible to readers: live
+hyperlinks, styled text, tables, images, and automatic tables of contents,
+among other advantages.  
 
-==How to Use This Template==
 
-To use this template you must first decide whether your GLEP is going to be an Informational or Standards Track GLEP.  Most GLEPs are Standards Track because they propose new functionality for some aspect of Gentoo Linux.  When in doubt, read GLEP 1 for details or contact the GLEP editors <glep@gentoo.org>.
-Once you've decided which type of GLEP yours is going to be, follow the directions below.
+Backwards Compatibility
+=======================
 
-* Make a copy of the source as described under "Abstract" and perform the following edits.
+Not a problem for this GLEP.  This section should be included *even* when it
+is only to state that there are no backwards compatibility issues.
 
-* Replace the "GLEP: 2" header with "GLEP: XXX" since you don't yet have a GLEP number assignment.
 
-* Change the Title header to the title of your GLEP.
+How to Use This Template
+========================
 
-* Leave the Version header alone; we'll take care of those when we add your GLEP to the wiki.
+To use this template you must first decide whether your GLEP is going to be an
+Informational or Standards Track GLEP.  Most GLEPs are Standards Track because
+they propose new functionality for some aspect of Gentoo Linux.  When in
+doubt, read GLEP 1 for details or contact the GLEP editors <glep@gentoo.org>.
 
-* Change the Author header to include your name, and optionally your email address.  Be sure to follow the format carefully: your name must appear first, and it must not be contained in parentheses.  Your email address may appear second (or it can be omitted) and if it appears, it must appear in angle brackets.
+Once you've decided which type of GLEP yours is going to be, follow the
+directions below.
 
-* If there is a forum thread or a mailing list for discussion of your new feature, add a Discussions-To header right after the Author header.  You should not add a Discussions-To header if the mailing list to be used is gentoo-dev@gentoo.org, or if discussions should be sent to you directly.  Most Informational GLEPs don't have a Discussions-To header.
+- Make a copy of this file (``.txt`` file, **not** HTML!) and perform
+  the following edits.
 
-* Change the Status header to "Draft".
+- Replace the "GLEP: 2" header with "GLEP: XXX" since you don't yet have
+  a GLEP number assignment.
 
-* For Standards Track GLEPs, change the Type header to "Standards Track".
+- Change the Title header to the title of your GLEP.
 
-* For Informational GLEPs, change the Type header to "Informational".
+- Leave the Version and Last-Modified headers alone; we'll take care
+  of those when we check your GLEP into CVS.
 
-* For Standards Track GLEPs, if your feature depends on the acceptance of some other currently in-development GLEP, add a Requires header right after the Type header.  The value should be the GLEP number of the GLEP yours depends on.  Don't add this header if your dependent feature is described in a Final GLEP.
+- Change the Author header to include your name, and optionally your
+  email address.  Be sure to follow the format carefully: your name must
+  appear first, and it must not be contained in parentheses.  Your email
+  address may appear second (or it can be omitted) and if it appears, it must
+  appear in angle brackets.  Your e-mail address
+  here will e automatically obfuscated.
 
-* Change the Created header to today's date.  Be sure to follow the format carefully: it must be in dd-mmm-yyyy format, where the mmm is the 3 English letter month abbreviation, i.e. one of Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.
+- If there is a forum thread or a mailing list for discussion 
+  of your new feature, add a Discussions-To header right after the Author
+  header.  You should not add a Discussions-To header if the mailing list to
+  be used is gentoo-dev@gentoo.org, or if discussions should be sent to you
+  directly.  Most Informational GLEPs don't have a Discussions-To header.
 
-* Leave Post-History alone for now; you'll add dates to this header each time you post your GLEP to gentoo-dev@gentoo.org.  If you posted your GLEP to the list on August 14, 2003 and September 3, 2003, the Post-History header would look like:
+- Change the Status header to "Draft".
 
-    Post-History: 14-Aug-2003, 03-Sept-2003
+- For Standards Track GLEPs, change the Type header to "Standards
+  Track".
 
-You must manually add new dates and check them in.  If you don't have check-in privileges, send your changes to the GLEP editors.
+- For Informational GLEPs, change the Type header to "Informational".
 
-* Add a Replaces header if your GLEP obsoletes an earlier GLEP.  The value of this header is the number of the GLEP that your new GLEP is replacing.  Only add this header if the older GLEP is in "final" form, i.e. is either Accepted, Final, or Rejected.  You aren't replacing an older open GLEP if you're submitting a competing idea.
-* Now write your Abstract, Rationale, and other content for your GLEP, replacing all of this gobbledygook with your own text. Be sure to adhere to the format guidelines below, specifically on the indentation requirements.
-* Update your References section.  You should leave the Copyright section as-is, since all new GLEPs are to be licensed under the Creative Commons Attribution-ShareAlike License, Version 3.0.
-* Send your GLEP submission to the GLEP editors at glep@gentoo.org.
+- For Standards Track GLEPs, if your feature depends on the acceptance
+  of some other currently in-development GLEP, add a Requires header right
+  after the Type header.  The value should be the GLEP number of the GLEP
+  yours depends on.  Don't add this header if your dependent feature is
+  described in a Final GLEP.
 
-==Wiki Markup GLEP Formatting Requirements==
+- Change the Created header to today's date.  Be sure to follow the
+  format carefully: it must be in ``dd-mmm-yyyy`` format, where the ``mmm`` is
+  the 3 English letter month abbreviation, i.e. one of Jan, Feb, Mar, Apr,
+  May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.
 
-The following is a GLEP-specific summary of Wiki Markup syntax.  For the sake of simplicity and brevity, much detail is omitted.  For more detail, see [[#Resources|Resources]] below. <nowiki><nowiki></nowiki> blocks  (in which no markup processing is done) are used for examples throughout, to illustrate the plaintext markup.
+- Leave Post-History alone for now; you'll add dates to this header
+  each time you post your GLEP to gentoo-dev@gentoo.org.  If you posted your
+  GLEP to the list on August 14, 2003 and September 3, 2003, the Post-History
+  header would look like::
 
-===General===
+      Post-History: 14-Aug-2003, 03-Sept-2003
 
-You must adhere to the convention of adding two spaces at the end of every sentence.  There are no longer line length restrictions when creating GLEPs.
+  You must manually add new dates and check them in.  If you don't have
+  check-in privileges, send your changes to the GLEP editors.
 
-===Section Headings===
+- Add a Replaces header if your GLEP obsoletes an earlier GLEP.  The
+  value of this header is the number of the GLEP that your new GLEP is
+  replacing.  Only add this header if the older GLEP is in "final" form, i.e.
+  is either Accepted, Final, or Rejected.  You aren't replacing an older open
+  GLEP if you're submitting a competing idea.
 
-GLEP headings must begin in column zero and the initial letter of each word must be capitalized as in book titles.  Acronyms should be in all capitals.  Section titles must be properly marked as such using the "=" (equals sign) character, with the number of equals corresponding to the level of the heading plus one, so two equals signs on each side for a first-level title, three on each side for a second-level title, and so on up to five levels.  For example:
-<pre>
-==First-Level Title==
-===Second-Level Title===
-====Third-Level Title====
-</pre>
-You shouldn't have more than five levels of sections in your GLEP.  If you do, you should consider rewriting it.
+- Now write your Abstract, Rationale, and other content for your GLEP,
+  replacing all of this gobbledygook with your own text. Be sure to adhere to
+  the format guidelines below, specifically on the indentation requirements.
 
-You must use two blank lines between the last line of a section's body and the next section heading.  If a subsection heading immediately follows a section heading, a single blank line in-between is sufficient.
+- Update your References and Copyright section.  Usually you'll place
+  your GLEP into the public domain, in which case just leave the Copyright
+  section alone.  Alternatively, you can use the `Open Publication License`__,
+  but public domain is still strongly preferred.
 
-The body of each section is not normally indented, although some constructs do use indentation, as described below.  Blank lines are used to separate constructs.
+  __ http://www.opencontent.org/openpub/
 
-===Paragraphs===
+- Send your GLEP submission to the GLEP editors at glep@gentoo.org.
 
-Paragraphs are left-aligned text blocks separated by blank lines.  Paragraphs are not indented unless they are part of an indented construct (such as a block quote or a list item). Wiki Markup formatting interprets newlines in a specific way. A single newline is treated as formatting and so there is no line inserted into the displayed product, but two newlines is interpreted as a line break and inserts a newline into the final product.  For example,
-this does not display a line break, but
 
-this has two newlines and therefore does.
+ReStructuredText GLEP Formatting Requirements
+=============================================
 
-===Inline Markup===
+The following is a GLEP-specific summary of reStructuredText syntax.  For the
+sake of simplicity and brevity, much detail is omitted.  For more detail, see
+`Resources`_ below.  `Literal blocks`_ (in which no markup processing is done)
+are used for examples throughout, to illustrate the plaintext markup.
 
-Portions of text within paragraphs and other text blocks may be styled.  For example:
 
-Text may be marked as ''emphasized'' (double apostrophe markup, typically shown in italics) or '''strongly emphasized''' (triple apostrophes, typically boldface).  Preformatted sections (set off using <nowiki><pre></nowiki> tags) are typically rendered in a monospaced typeface.  No further markup recognition is done within the tags,  so they're safe for any kind of code snippets.  Alternatively, if the snippet should not be set aside in a monospaced typeface, the <nowiki><nowiki></nowiki> tag may be used, but this strips line breaks and other whitespace.
+General
+-------
 
-===Block Quotes===
+You must adhere to the convention of adding two spaces at the end of every
+sentence.  You should fill your paragraphs to column 70, but under no
+circumstances should your lines extend past column 79.  If your code samples
+spill over column 79, you should rewrite them.
 
-Block quotes consist of indented body elements.  For example:
+
+Section Headings
+----------------
+
+GLEP headings must begin in column zero and the initial letter of each word
+must be capitalized as in book titles.  Acronyms should be in all capitals.
+Section titles must be adorned with an underline, a single repeated
+punctuation character, which begins in column zero and must extend at least as
+far as the right edge of the title text (4 characters minimum).  First-level
+section titles are underlined with "=" (equals signs), second-level section
+titles with "-" (hyphens), and third-level section titles with "'" (single
+quotes or apostrophes).  For example::
+
+    First-Level Title
+    =================
+
+    Second-Level Title
+    ------------------
+
+    Third-Level Title
+    '''''''''''''''''
+
+If there are more than three levels of sections in your GLEP, you may insert
+overline/underline-adorned titles for the first and second levels as follows::
+
+    ============================
+    First-Level Title (optional)
+    ============================
+
+    -----------------------------
+    Second-Level Title (optional)
+    -----------------------------
+
+    Third-Level Title
+    =================
+
+    Fourth-Level Title
+    ------------------
+
+    Fifth-Level Title
+    '''''''''''''''''
+
+You shouldn't have more than five levels of sections in your GLEP.  If you do,
+you should consider rewriting it.
+
+You must use two blank lines between the last line of a section's body and the
+next section heading.  If a subsection heading immediately follows a section
+heading, a single blank line in-between is sufficient.
+
+The body of each section is not normally indented, although some constructs do
+use indentation, as described below.  Blank lines are used to separate
+constructs.
+
+
+Paragraphs
+----------
+
+Paragraphs are left-aligned text blocks separated by blank lines.  Paragraphs
+are not indented unless they are part of an indented construct (such as a
+block quote or a list item).
+
+
+Inline Markup
+-------------
+
+Portions of text within paragraphs and other text blocks may be
+styled.  For example::
+
+    Text may be marked as *emphasized* (single asterisk markup,
+    typically shown in italics) or **strongly emphasized** (double
+    asterisks, typically boldface).  ``Inline literals`` (using double
+    backquotes) are typically rendered in a monospaced typeface.  No
+    further markup recognition is done within the double backquotes,
+    so they're safe for any kind of code snippets.
+
+
+Block Quotes
+------------
+
+Block quotes consist of indented body elements.  For example::
 
     This is a paragraph.
 
         This is a block quote.
+
         A block quote may contain many paragraphs.
 
-Block quotes are used to quote extended passages from other sources. Block quotes may be nested inside other body elements.  Use a 4-space tab per indent level.  A contiguous block quote should not have extra spacing between lines; this causes the wiki to break them up into separate quotes.
+Block quotes are used to quote extended passages from other sources.
+Block quotes may be nested inside other body elements.  Use a 4-space tab
+per indent level.
+
+
+Literal Blocks
+--------------
+
+..  
+    In the text below, double backquotes are used to denote inline
+    literals.  "``::``" is written so that the colons will appear in a
+    monospaced font; the backquotes (``) are markup, not part of the
+    text.  See "Inline Markup" above.
+
+    By the way, this is a comment, described in "Comments" below.
+
+Literal blocks are used for code samples or preformatted ASCII art. To
+indicate a literal block, preface the indented text block with
+"``::``" (two colons).  The literal block continues until the end of
+the indentation.  Indent the text block by a tab.  For example::
+
+    This is a typical paragraph.  A literal block follows.
+
+    ::
+
+        for a in [5,4,3,2,1]:   # this is program code, shown as-is
+            print a
+        print "it's..."
+        # a literal block continues until the indentation ends
+
+The paragraph containing only "``::``" will be completely removed from
+the output; no empty paragraph will remain.  "``::``" is also
+recognized at the end of any paragraph.  If immediately preceded by
+whitespace, both colons will be removed from the output.  When text
+immediately precedes the "``::``", *one* colon will be removed from
+the output, leaving only one colon visible (i.e., "``::``" will be
+replaced by "``:``").  For example, one colon will remain visible
+here::
+
+    Paragraph::
+
+        Literal block
+
+
+Lists
+-----
+
+Bullet list items begin with one of "-", "*", or "+" (hyphen,
+asterisk, or plus sign), followed by whitespace and the list item
+body.  List item bodies must be left-aligned and indented relative to
+the bullet; the text immediately after the bullet determines the
+indentation.  For example::
+
+    This paragraph is followed by a list.
 
-===Literal Blocks===
+    * This is the first bullet list item.  The blank line above the
+      first list item is required; blank lines between list items
+      (such as below this paragraph) are optional.
 
-<!--
-In the text below, <pre> and <nowiki> tags are used to indicate to the markup parser that a tag should be displayed literally. Thus, <nowiki><pre></nowiki> and <nowiki><nowiki></nowiki> are displayed as <pre> and <nowiki> respectively.  See "Inline Markup" above.
+    * This is the first paragraph in the second item in the list.
 
-By the way, this is a comment, described in "Comments" below.
--->
-Literal blocks are used for code samples or preformatted ASCII art.  To indicate a literal block, preface the text block with <nowiki><pre></nowiki>.  The literal block continues until the <nowiki></pre></nowiki> block is reached.  For example:
+      This is the second paragraph in the second item in the list.
+      The blank line above this paragraph is required.  The left edge
+      of this paragraph lines up with the paragraph above, both
+      indented relative to the bullet.
 
-This is a typical paragraph.  A literal block follows.
+      - This is a sublist.  The bullet lines up with the left edge of
+        the text blocks above.  A sublist is a new list so requires a
+        blank line above and below.
 
-<pre>
-for a in [5,4,3,2,1]:   # this is program code, shown as-is
-    print a
-print "it's..."
-</pre>
+    * This is the third item of the main list.
 
-===Lists===
+    This paragraph is not part of the list.
 
-Bullet list items begin with "*" (asterisk) for a bulleted list followed by whitespace and the list item body.  Sub-lists may be created by adding additional list symbols, so "**" would add a bullet for a sub-list, "***" would add a bullet for a sub-sub-list, and so on.  For example:
+Enumerated (numbered) list items are similar, but use an enumerator
+instead of a bullet.  Enumerators are numbers (1, 2, 3, ...), letters
+(A, B, C, ...; uppercase or lowercase), or Roman numerals (i, ii, iii,
+iv, ...; uppercase or lowercase), formatted with a period suffix
+("1.", "2."), parentheses ("(1)", "(2)"), or a right-parenthesis
+suffix ("1)", "2)").  For example::
 
-This paragraph is followed by a list.
+    1. As with bullet list items, the left edge of paragraphs must
+       align.
 
-* This is the first bullet list item.
-* This is the first paragraph in the second item in the list. <br />This is the second paragraph in the second item in the list. In order to add extra paragraphs to a list item, add the <nowiki><br /></nowiki> tag before the second paragraph. 
-** This is is a sublist.
-* This is the third item of the main list.
+    2. Each list item may contain multiple paragraphs, sublists, etc.
 
-This paragraph is not part of the list.
+       This is the second paragraph of the second list item.
 
-Enumerated (numbered) list items are similar, but use the "#" symbol instead of the "*" symbol.
+       a) Enumerated lists may be nested.
+       b) Blank lines may be omitted between list items.
 
-# First entry of an enumerated list.
-# Each list item may contain multiple paragraphs, sublists, etc. <br />This is the second paragraph of the second list item.
-## Enumerated lists may be nested.
-## Keep in mind that you should not have extra newlines between list elements, since they must be in a contiguous group in order to be numbered properly
+Definition lists are written like this::
 
-Definition lists are written like this:
+    what
+        Definition lists associate a term with a definition.
 
-;what
-:Definition lists associate a term with a definition.
+    how
+        The term is a one-line phrase, and the definition is one
+        or more paragraphs or body elements, indented relative to
+        the term.
 
-;how
-:the term is a one-line phrase preceded by ; (a semicolon), and the definition is preceded by : (a colon).
 
-===Tables===
+Tables
+------
 
-Simple tables are easy and compact:
+Simple tables are easy and compact::
 
     =====  =====  =======
       A      B    A and B
@@ -179,7 +365,7 @@ Simple tables are easy and compact:
 
 There must be at least two columns in a table (to differentiate from
 section titles).  Column spans use underlines of hyphens ("Inputs"
-spans the first two columns):
+spans the first two columns)::
 
     =====  =====  ======
        Inputs     Output
@@ -208,75 +394,223 @@ consist of multiple lines.  For example::
              list (row 3, column 2).
     =====  =========================
 
-===Hyperlinks===
 
-When referencing an external web page in the body of a GLEP, you should include the title of the page in the text, with either an inline hyperlink reference to the URL or a footnote reference (see [[#Footnotes|Footnotes]] below).  Do not include the URL in the body text of the GLEP.
+Hyperlinks
+----------
+
+When referencing an external web page in the body of a GLEP, you should
+include the title of the page in the text, with either an inline
+hyperlink reference to the URL or a footnote reference (see
+`Footnotes`_ below).  Do not include the URL in the body text of the
+GLEP.
+
+Hyperlink references use backquotes and a trailing underscore to mark
+up the reference text; backquotes are optional if the reference text
+is a single word.  For example::
+
+    In this paragraph, we refer to the `Python web site`_.
+
+An explicit target provides the URL.  Put targets in a References
+section at the end of the GLEP, or immediately after the reference.
+Hyperlink targets begin with two periods and a space (the "explicit
+markup start"), followed by a leading underscore, the reference text,
+a colon, and the URL (absolute or relative)::
+
+    .. _Python web site: http://www.python.org/
+
+The reference text and the target text must match (although the match
+is case-insensitive and ignores differences in whitespace).  Note that
+the underscore trails the reference text but precedes the target text.
+If you think of the underscore as a right-pointing arrow, it points
+*away* from the reference and *toward* the target.
+
+The same mechanism can be used for internal references.  Every unique
+section title implicitly defines an internal hyperlink target.  We can
+make a link to the Abstract section like this::
+
+    Here is a hyperlink reference to the `Abstract`_ section.  The
+    backquotes are optional since the reference text is a single word;
+    we can also just write: Abstract_.
+
+Footnotes containing the URLs from external targets will be generated
+automatically at the end of the References section of the GLEP, along
+with footnote references linking the reference text to the footnotes.
+
+Text of the form "GLEP x" or "RFC x" (where "x" is a number) will be
+linked automatically to the appropriate URLs.
+
+
+Footnotes
+---------
+
+Footnote references consist of a left square bracket, a number, a
+right square bracket, and a trailing underscore::
+
+    This sentence ends with a footnote reference [1]_.
+
+Whitespace must precede the footnote reference.  Leave a space between
+the footnote reference and the preceding word.
+
+When referring to another GLEP, include the GLEP number in the body
+text, such as "GLEP 1".  The title may optionally appear.  Add a
+footnote reference following the title.  For example::
+
+    Refer to GLEP 1 [2]_ for more information.
+
+Add a footnote that includes the GLEP's title and author.  It may
+optionally include the explicit URL on a separate line, but only in
+the References section.  Footnotes begin with ".. " (the explicit
+markup start), followed by the footnote marker (no underscores),
+followed by the footnote body.  For example::
+
+    References
+    ==========
+
+    .. [2] GLEP 1, "GLEP Purpose and Guidelines", Goodyear, Warsaw, Hylton
+       (http://glep.gentoo.org/glep-0001.html)
+
+If you decide to provide an explicit URL for a GLEP, please use this as
+the URL template::
+
+    http://glep.gentoo.org/glep-xxxx.html
+
+GLEP numbers in URLs must be padded with zeros from the left, so as to
+be exactly 4 characters wide, however GLEP numbers in the text are
+never padded.
+
+During the course of developing your GLEP, you may have to add, remove,
+and rearrange footnote references, possibly resulting in mismatched
+references, obsolete footnotes, and confusion.  Auto-numbered
+footnotes allow more freedom.  Instead of a number, use a label of the
+form "#word", where "word" is a mnemonic consisting of alphanumerics
+plus internal hyphens, underscores, and periods (no whitespace or
+other characters are allowed).  For example::
+
+    Refer to GLEP 1 [#GLEP-1]_ for more information.
+
+    References
+    ==========
+
+    .. [#GLEP-1] GLEP 1, "GLEP Purpose and Guidelines", Goodyear
+       http://glep.gentoo.org/glep-0001.html
+
+Footnotes and footnote references will be numbered automatically, and
+the numbers will always match.  Once a GLEP is finalized, auto-numbered
+labels should be replaced by numbers for simplicity.
+
+
+Images
+------
+
+If your GLEP contains a diagram, you may include it in the processed
+output using the "image" directive::
+
+    .. image:: diagram.png
+
+Any browser-friendly graphics format is possible: .png, .jpeg, .gif,
+.tiff, etc.
+
+Since this image will not be visible to readers of the GLEP in source
+text form, you should consider including a description or ASCII art
+alternative, using a comment (below).
+
+
+Comments
+--------
+
+A comment block is an indented block of arbitrary text immediately
+following an explicit markup start: two periods and whitespace.  Leave
+the ".." on a line by itself to ensure that the comment is not
+misinterpreted as another explicit markup construct.  Comments are not
+visible in the processed document.  For the benefit of those reading
+your GLEP in source form, please consider including a descriptions of
+or ASCII art alternatives to any images you include.  For example::
+
+     .. image:: dataflow.png
+
+     ..
+        Data flows from the input module, through the "black box"
+        module, and finally into (and through) the output module.
 
-Hyperlink references can be accomplished using single brackets. These brackets should contain the link, a space, then the text to display for the hyperlink. For example:
 
-<pre>In this paragraph, we refer to the [http://www.python.org/ Python web site]</pre>
 
-There are certain limitations to embedding hyperlinks like this, mostly related to special characters requiring replacement. [http://en.wikipedia.org/wiki/Help:Wiki_markup#External_links Wikipedia] has a list of these special cases.
+Escaping Mechanism
+------------------
 
-A similar mechanism can be used for internal references or references within the wiki, although these use double brackets instead of single brackets and a vertical pipe to differentiate between the target and the display text.  Every unique section title implicitly defines an internal hyperlink target.  We can make a link to the Abstract section like this:
+reStructuredText uses backslashes ("``\``") to override the special
+meaning given to markup characters and get the literal characters
+themselves.  To get a literal backslash, use an escaped backslash
+("``\\``").  There are two contexts in which backslashes have no
+special meaning: `literal blocks`_ and inline literals (see `Inline
+Markup`_ above).  In these contexts, no markup recognition is done,
+and a single backslash represents a literal backslash, without having
+to double up.
 
-<pre>Here is a hyperlink reference to the [[#Abstract|Abstract]] section.</pre>
+If you find that you need to use a backslash in your text, consider
+using inline literals or a literal block instead.
 
-===Footnotes===
 
-<nowiki>
-The references section will be generated via the Mediawiki "Cite" extension. In order to add a refence, use <ref name="(name)">(Link/name of source)</ref>.  Any subsequent references to the same source may use <ref name="(name)"/> to refer to the same source.  All references should have a name associated with them. Under the References section, the tag <references/> should be used to output all of the references in a list. </nowiki>
+Habits to Avoid
+===============
 
-When referring to another GLEP, include the GLEP number in the body text, such as "GLEP 1".  The title may optionally appear.  Add a footnote reference following the title, which should include the title and author's name, and may optionally include an explicit URL. If you decide to provide an explicit URL for a GLEP, please use this as the URL template:
+Many programmers who are familiar with TeX often write quotation marks
+like this::
 
-    http://wiki.gentoo.org/wiki/GLEP:xxxx.html <!--Subject to chance once we actually get the namespace -->
+    `single-quoted' or ``double-quoted''
 
-A citation of GLEP 1 done like this might look like:
+Backquotes are significant in reStructuredText, so this practice
+should be avoided.  For ordinary text, use ordinary 'single-quotes' or
+"double-quotes".  For inline literal text (see `Inline Markup`_
+above), use double-backquotes::
 
-<pre>Refer to GLEP 1 for more information.<ref name="glep1">
-GLEP 1, GLEP Purpose and Guidelines, Goodyear, (http://wiki.gentoo.org/wiki/GLEP:0001.html)</ref></pre>
+    ``literal text: in here, anything goes!``
 
 
-GLEP numbers in URLs must be padded with zeros from the left, so as to be exactly 4 characters wide, however GLEP numbers in the text are never padded. 
+Resources
+=========
 
-Footnotes and footnote references will be numbered and inserted automatically, and the numbers will always match. 
+Many other constructs and variations are possible.  For more details
+about the reStructuredText markup, in increasing order of
+thoroughness, please see:
 
-===Images===
+* `A ReStructuredText Primer`__, a gentle introduction.
 
-If your GLEP contains a diagram, you first must upload it at the [[Special:Upload|upload page.] You may then include it in the processed
-output using a File: tag:
+  __ http://docutils.sourceforge.net/docs/rst/quickstart.html
 
-<pre>[[File:diagram.png]]</pre>
+* `Quick reStructuredText`__, a users' quick reference.
 
-Any browser-friendly graphics format is possible: .png, .jpeg, .gif, .tiff, etc.
+  __ http://docutils.sourceforge.net/docs/rst/quickref.html
 
-Since this image will not be visible to readers of the GLEP in source text form, you should consider including a description or ASCII art alternative, using a comment (below).
+* `reStructuredText Markup Specification`__, the final authority.
 
-===Comments===
+  __ http://docutils.sourceforge.net/spec/rst/reStructuredText.html
 
-A comment block is a block of markup text that will not appear in the final page.  It is delimited by <nowiki><!-- and --></nowiki>, and so looks like this:
+The processing of reStructuredText GLEPs is done using Docutils_.  If
+you have a question or require assistance with reStructuredText or
+Docutils, please `post a message`_ to the `Docutils-Users mailing
+list`_.  The `Docutils project web site`_ has more information.
 
-    <pre><!--Here is a comment!--></pre>
+.. _Docutils: http://docutils.sourceforge.net/
+.. _post a message:
+   mailto:docutils-users@lists.sourceforge.net?subject=GLEPs
+.. _Docutils-Users mailing list:
+   http://lists.sourceforge.net/lists/listinfo/docutils-users
+.. _Docutils project web site: http://docutils.sourceforge.net/
 
-Comments are not visible in the processed document.  For the benefit of those reading your GLEP in source form, please consider including a descriptions of or ASCII art alternatives to any images you include.  For example:
 
-<pre>
-[[File:dataflow.png]]
-<!--Data flows from the input module, through the "black box" module, and finally into (and through) the output module.-->
-</pre>
+References
+==========
 
-==Resources==
+.. [#PYTHON] http://www.python.org
 
-Wiki Markup has a large number of formatting options, this guide should only be considered to be a basic introduction. For more information, the following links may be useful:
+.. [#PEP12] http://www.python.org/peps/pep-0012.html
 
-* The Wikipedia Cheat Sheet, which is a quick reference for basic formatting. <ref name="wikicheatsheet">http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet</ref>
-* The Wikipedia help page on Wiki Markup, which is much more in-depth and has many subpages for specific topics. <ref name="wikimarkupguide">http://en.wikipedia.org/wiki/Help:Wiki_markup</ref>
+.. [#GLEP1] GLEP 1, GLEP Purpose and Guidelines, Goodyear, 
+   (http://glep.gentoo.org/glep-0001.html)
 
-==References==
 
-This section should include a <nowiki><references /></nowiki> tag, which will automatically generate all footnotes from the above document.
-<references/>
+Copyright
+=========
 
-==Copyright==
+This document has been placed in the public domain.
 
-This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/.
-- 
2.14.1

[gentoo-project] [PATCH 17/18] glep-0002: Update headers per GLEP 1 changes (example)

[Michał Górny]

The actual update for headers of all GLEPs will be prepared later.
---
 glep-0002.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/glep-0002.txt b/glep-0002.txt
index 06a1964..e39e23e 100644
--- a/glep-0002.txt
+++ b/glep-0002.txt
@@ -1,13 +1,15 @@
+---
 GLEP: 2
 Title: Sample ReStructuredText GLEP Template
-Version: $Revision$
-Last-Modified: $Date$
+Version: 3
+Last-Modified: 2017-09-14
 Author:	Grant Goodyear <g2boojum@gentoo.org>,
 Status: Active
 Type: Informational
 Content-Type: text/x-rst
-Created: 31 May 2003
-Post-History: 2-Jun-2003, 17-Dec-2013
+Created: 2003-05-31
+Post-History: 2003-06-02, 2013-12-17
+---
 
 
 Credits
-- 
2.14.1

[gentoo-project] [PATCH 18/18] glep-0045: Mark Final since GLEP 1 now uses ISO 8601 dates

[Michał Górny]

---
 glep-0045.txt | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/glep-0045.txt b/glep-0045.txt
index eb2fa09..afaf62a 100644
--- a/glep-0045.txt
+++ b/glep-0045.txt
@@ -3,17 +3,12 @@ Title: GLEP date format
 Version: $Revision$
 Author: Henrik Brix Andersen <brix@gentoo.org>
 Last-Modified: $Date$
-Status: Deferred
+Status: Final
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 13-Dec-2005
 Post-History: 13-Dec-2005
 
-Status
-======
-
-No progress, marked as Deferred by GLEP editor creffett.
-
 Abstract
 ========
 
-- 
2.14.1

Re: [gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Daniel Campbell]

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

On 09/14/2017 12:03 PM, Michał Górny wrote:
> Hi, everyone.
> 
> Following the backporting of all GLEP changes from the wiki to my draft
> repository [1] (which is still open for a separate review), I have
> prepared an update for GLEP 1 & 2. For your convenience, the update
> is both sent as git patches in reply to this mail, and provided
> as a GH pull request [2].
> 
> The notable changes are:
> 
> 1. A new git-based workflow is introduced that is a combination
>    of the old CVS workflow and the MW workflow (wrt access
>    restrictions). The developers create branches or fork the GLEP
>    repository, and work on their drafts there. GLEP editors merge
>    changes into master to make them official.
> 
> 2. The old ReST markup is restored. Previously, GLEPs allowed also
>    GuideXML but this is not supported anymore.
> 
> 3. The complete set of GLEP headers is restored, and they are updated
>    for the modern workflow:
> 
>    - Last-Updated needs to be set manually,
>    - Version is updated manually and is semantic,
>    - all dates use ISO 8601 (GLEP 45).
> 
> 4. Two minor changes are made for better interoperability (i.e. less
>    custom code and better support for external tools):
> 
>    - source files are renamed from .txt to .rst,
>    - headers are surrounded by '---' to be compatible with YAML Front
>      Matter.
> 
> 5. GLEP workflow is updated to account for additional statuses in use:
> 
>    - 'Withdrawn' when author withdraws the GLEP (used in 4 GLEPs),
>    - 'Moribund' when GLEP is obsoleted without a replacement
>      (historically used in 1 GLEP but the need was discussed recently).
> 
> Please review and comment.
> 
> [1]:https://github.com/gentoo/glep-draft/pull/1
> [2]:https://github.com/gentoo/glep-draft/pull/2
> 
> --
> Best regards,
> Michał Górny
> 
> 
Looks good. Migrating to purely text files, independent of framework, is
a good step forward. K-9 zapped a mail I tried to send to you in another
reply saying such, so I felt it best to repeat it here. I like how we're
referencing and leveraging existing standards to improve interoperability.

If I had to find a nitpick, it's a minor feature request: can we get a
GLEP template file later on, to aid the initial drafting process? I
didn't see it in the repo.
-- 
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 --]

[gentoo-project] [PATCH 19/18] glep-0001: Require YAML conformance from the preamble

[Michał Górny]

Most of the GLEP headers can be parsed by a standard YAML parsers. There
are currently two exceptions to that (due to title starting with "),
and they are easy enough to fix. Therefore, require conformance with
YAML to make sure we do not have to reinvent header parsing.
---
 glep-0001.txt | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 2112d41..78e76ce 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -236,8 +236,9 @@ GLEP Header
 
 Every GLEP has certain attributes associated with it. When a GLEP is sent
 to the mailing lists for discussion, it should begin with an RFC 2822 style
-header preamble between two triple-dashed lines.  Headers marked with "*" are
-optional. All other headers are required.
+header preamble between two triple-dashed lines. For interoperability,
+the header preamble should also conform to the YAML standard [#YAML]_.
+Headers marked with "*" are optional. All other headers are required.
 
 ::
 
@@ -379,6 +380,8 @@ References and Footnotes
 
 .. [#GLEP2] http://glep.gentoo.org/glep-0002.html
 
+.. [#YAML] http://yaml.org/
+
 
 Copyright
 =========
-- 
2.14.1

Re: [gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Robin H. Johnson]

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

On Thu, Sep 14, 2017 at 02:58:55PM -0700, Daniel Campbell wrote:
> If I had to find a nitpick, it's a minor feature request: can we get a
> GLEP template file later on, to aid the initial drafting process? I
> didn't see it in the repo.
GLEP2 is the template; did you want something else as a template?

-- 
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-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Robin H. Johnson]

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

On Thu, Sep 14, 2017 at 09:03:08PM +0200, Michał Górny wrote:
> Hi, everyone.
> 
> Following the backporting of all GLEP changes from the wiki to my draft
> repository [1] (which is still open for a separate review), I have
> prepared an update for GLEP 1 & 2. For your convenience, the update
> is both sent as git patches in reply to this mail, and provided
> as a GH pull request [2].
This series looks good to me, but I'd suggest some more eyeballs before
it gets merged.

-- 
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-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Daniel Campbell]

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

On 09/14/2017 04:28 PM, Robin H. Johnson wrote:
> On Thu, Sep 14, 2017 at 02:58:55PM -0700, Daniel Campbell wrote:
>> If I had to find a nitpick, it's a minor feature request: can we get a
>> GLEP template file later on, to aid the initial drafting process? I
>> didn't see it in the repo.
> GLEP2 is the template; did you want something else as a template?
> 
I was thinking something like a skeleton file. GLEP 2 is fine
documentation, but we already have ebuild and other skel files. I
figured it'd be useful for this repository as well.

-- 
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-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Michał Górny]

W dniu czw, 14.09.2017 o godzinie 14∶58 -0700, użytkownik Daniel
Campbell napisał:
> If I had to find a nitpick, it's a minor feature request: can we get a
> GLEP template file later on, to aid the initial drafting process? I
> didn't see it in the repo.

I see your point. I always took some random late GLEP and wiped out
the contents. Maybe having a skel file with just the headings and empty
headers wouldn't be such a bad idea after all.

I'm wondering if it belongs in the GLEP repo though. Maybe just
skel.rst? (given that www globs on glep-[0-9]...)

-- 
Best regards,
Michał Górny

GLEP non-compliance report (was: [gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow)

[Michał Górny]

W dniu czw, 14.09.2017 o godzinie 21∶03 +0200, użytkownik Michał Górny
napisał:
> 3. The complete set of GLEP headers is restored, and they are updated
>    for the modern workflow:
> 
>    - Last-Updated needs to be set manually,
>    - Version is updated manually and is semantic,
>    - all dates use ISO 8601 (GLEP 45).
> 
> 4. Two minor changes are made for better interoperability (i.e. less
>    custom code and better support for external tools):
> 
>    - source files are renamed from .txt to .rst,
>    - headers are surrounded by '---' to be compatible with YAML Front
>      Matter.
> 
> 5. GLEP workflow is updated to account for additional statuses in use:
> 
>    - 'Withdrawn' when author withdraws the GLEP (used in 4 GLEPs),
>    - 'Moribund' when GLEP is obsoleted without a replacement
>      (historically used in 1 GLEP but the need was discussed recently).

And here's a small report on what doesn't match the spec besides
the obvious changes (date format, ---).

Strict violations:

1. GLEPs 57..61 (@robbat2) used 'Updated' header with a list of dates
that's not allowed by the spec.

2. GLEPs 59..61 (@robbat2) used 'Updates: 44', probably to indicate that
they extend the format specified in GLEP 44.

3. GLEPs 31, 33, 40, 57 used 'Approved' header with a date.

4. GLEP 21 used 'Discussed-To' header for gentoo-portage-dev@ (probably
a typo of 'Discussions-To'.

5. GLEP 11 used 'Discussions-To: gentoo-dev@...'. This header was
explicitly removed from GLEP 1 as not very useful, and was probably used
contrary to the original use anyway.

6. GLEP 4 used 'Editor' header.

7. GLEPs 10, 12 were missing 'Content-Type'.

8. GLEP 15 used 'Status: Approved', probably 'Accepted' was meant.


YAML violations not strictly required by the spec:

a. most of GLEPs copied <tab> between 'Author:' and the name
from GLEP 2; I've replaced all of that with spaces.

b. GLEPs 28 and 30 use quoted word in the beginning of the title which
confuses the YAML parser. It could be solved by adding extra quoting
around the whole line or using fancy quotes (“”) instead of plain "".

-- 
Best regards,
Michał Górny

Re: [gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Daniel Campbell]

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

On 09/14/2017 11:31 PM, Michał Górny wrote:
> W dniu czw, 14.09.2017 o godzinie 14∶58 -0700, użytkownik Daniel
> Campbell napisał:
>> If I had to find a nitpick, it's a minor feature request: can we get a
>> GLEP template file later on, to aid the initial drafting process? I
>> didn't see it in the repo.
> 
> I see your point. I always took some random late GLEP and wiped out
> the contents. Maybe having a skel file with just the headings and empty
> headers wouldn't be such a bad idea after all.
> 
> I'm wondering if it belongs in the GLEP repo though. Maybe just
> skel.rst? (given that www globs on glep-[0-9]...)
>
skel.rst would work I think; any file name that didn't disrupt
automation would be good enough, though. No real preference.

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

[gentoo-project] [PATCH 20/18] glep-0001: Attempt a more logical ordering of GLEP headers

[Michał Górny]

Attempt to reorder headers so that they are more logically ordered,
to improve the chance that people will actually remember the order.

The order is as follows:

1. basic title page data (number, title, author),
2. type and status (which looks somewhat subordinate to type),
3. version (next to the dates) -- more frequently updated,
4. all three dates, in time order -- Created, Last-Modified, Posted,
5. Content-Type -- last non-optional header that never changes,
6. optional GLEP-ref headers -- Requires, Replaces and Replaced-To.
---
 glep-0001.txt | 43 +++++++++++++++++++++----------------------
 1 file changed, 21 insertions(+), 22 deletions(-)

diff --git a/glep-0001.txt b/glep-0001.txt
index 78e76ce..6d4610e 100644
--- a/glep-0001.txt
+++ b/glep-0001.txt
@@ -244,32 +244,21 @@ Headers marked with "*" are optional. All other headers are required.
 
     ---
     GLEP: <glep number>
-    Version: <major>[.<minor>]
-    Last-Modified: <date of last update>
     Title: <glep title>
     Author: <list of authors' real names and optionally, email addrs>
+    Type: <Informational | Standards Track>
     Status: <Draft | Active | Accepted | Deferred | Withdrawn | Rejected |
              Final | Replaced | Moribund>
-    Type: <Informational | Standards Track>
-    Content-Type: <text/x-rst>
+    Version: <major>[.<minor>]
     Created: <date created on>
+    Last-Modified: <date of last update>
     Post-History: <dates of postings to mailing lists>
+    Content-Type: <text/x-rst>
   * Requires: <glep numbers>
   * Replaces: <glep number>
   * Replaced-By: <glep number>
     ---
 
-The Version field specifies the current version of the GLEP. The Version
-consists of a major version, optionally followed by a minor version (if
-non-zero). Every GLEP starts at version 1 which is successively incremented
-as changes are merged to the GLEP.
-
-The major version number should be incremented (and minor reset to zero)
-whenever the meaning of the GLEP changes. The minor version number should
-be incremented for changes that do not affect the basic meaning (e.g.
-clarifications, reference implementation updates). Editorial changes should
-be merged without increasing the version.
-
 The Author header lists the names, and optionally the email addresses
 of all the authors/owners of the GLEP.  Anybody who submits changes to
 the GLEP should be added to this field.The format of the Author header
@@ -289,16 +278,26 @@ following RFC 2822 continuation line conventions.
 The Type header specifies the type of GLEP: Informational or Standards
 Track.
 
+The Version field specifies the current version of the GLEP. The Version
+consists of a major version, optionally followed by a minor version (if
+non-zero). Every GLEP starts at version 1 which is successively incremented
+as changes are merged to the GLEP.
+
+The major version number should be incremented (and minor reset to zero)
+whenever the meaning of the GLEP changes. The minor version number should
+be incremented for changes that do not affect the basic meaning (e.g.
+clarifications, reference implementation updates). Editorial changes should
+be merged without increasing the version.
+
+The Created header records the date that the GLEP was assigned a number,
+Last-Modified specifies the date that the GLEP was last updated in the master
+branch, while Post-History is used to record the dates of when new versions
+of the GLEP are posted to the appropriate mailing list.  All three headers
+should be in ISO 8601 ``yyyy-mm-dd`` format, e.g. 2001-08-14.
+
 The format of a GLEP is specified with a Content-Type header, which
 must be "text/x-rst" for ReStructuredText GLEPs (see GLEP 2 [#GLEP2]_).
 
-The Last-Modified header specifies the date that the GLEP was last updated
-in the master branch.
-The Created header records the date that the GLEP was assigned a number, while
-Post-History is used to record the dates of when new versions of the GLEP are
-posted to gentoo-dev.  All three headers should be in ISO 8601 ``yyyy-mm-dd``
-format, e.g. 2001-08-14.
-
 GLEPs may have a Requires header, indicating the GLEP numbers that this GLEP
 depends on.
 
-- 
2.14.1

Re: [gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Michał Górny]

W dniu czw, 14.09.2017 o godzinie 23∶45 -0700, użytkownik Daniel
Campbell napisał:
> On 09/14/2017 11:31 PM, Michał Górny wrote:
> > W dniu czw, 14.09.2017 o godzinie 14∶58 -0700, użytkownik Daniel
> > Campbell napisał:
> > > If I had to find a nitpick, it's a minor feature request: can we get a
> > > GLEP template file later on, to aid the initial drafting process? I
> > > didn't see it in the repo.
> > 
> > I see your point. I always took some random late GLEP and wiped out
> > the contents. Maybe having a skel file with just the headings and empty
> > headers wouldn't be such a bad idea after all.
> > 
> > I'm wondering if it belongs in the GLEP repo though. Maybe just
> > skel.rst? (given that www globs on glep-[0-9]...)
> > 
> 
> skel.rst would work I think; any file name that didn't disrupt
> automation would be good enough, though. No real preference.
> 

OTOH, I think we'll start by adding it to gentoo syntax packages for our
editors, so e.g. typing:

$ vim glep-0100.rst

you'd get the skel in place. I guess we'll see how good coverage that
has, and then decide if we need another skel in the repo.

-- 
Best regards,
Michał Górny

Re: [gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Daniel Campbell]

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

On 09/14/2017 11:54 PM, Michał Górny wrote:
> W dniu czw, 14.09.2017 o godzinie 23∶45 -0700, użytkownik Daniel
> Campbell napisał:
>> On 09/14/2017 11:31 PM, Michał Górny wrote:
>>> W dniu czw, 14.09.2017 o godzinie 14∶58 -0700, użytkownik Daniel
>>> Campbell napisał:
>>>> If I had to find a nitpick, it's a minor feature request: can we get a
>>>> GLEP template file later on, to aid the initial drafting process? I
>>>> didn't see it in the repo.
>>>
>>> I see your point. I always took some random late GLEP and wiped out
>>> the contents. Maybe having a skel file with just the headings and empty
>>> headers wouldn't be such a bad idea after all.
>>>
>>> I'm wondering if it belongs in the GLEP repo though. Maybe just
>>> skel.rst? (given that www globs on glep-[0-9]...)
>>>
>>
>> skel.rst would work I think; any file name that didn't disrupt
>> automation would be good enough, though. No real preference.
>>
> 
> OTOH, I think we'll start by adding it to gentoo syntax packages for our
> editors, so e.g. typing:
> 
> $ vim glep-0100.rst
> 
> you'd get the skel in place. I guess we'll see how good coverage that
> has, and then decide if we need another skel in the repo.
> 
Now that you mention it, putting it into syntax packages seems cleaner
and editors could get automatic support. *And* this repository doesn't
have to be touched...

Maybe we have a winner? :p

-- 
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-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Michał Górny]

W dniu pią, 15.09.2017 o godzinie 00∶04 -0700, użytkownik Daniel
Campbell napisał:
> On 09/14/2017 11:54 PM, Michał Górny wrote:
> > W dniu czw, 14.09.2017 o godzinie 23∶45 -0700, użytkownik Daniel
> > Campbell napisał:
> > > On 09/14/2017 11:31 PM, Michał Górny wrote:
> > > > W dniu czw, 14.09.2017 o godzinie 14∶58 -0700, użytkownik Daniel
> > > > Campbell napisał:
> > > > > If I had to find a nitpick, it's a minor feature request: can we get a
> > > > > GLEP template file later on, to aid the initial drafting process? I
> > > > > didn't see it in the repo.
> > > > 
> > > > I see your point. I always took some random late GLEP and wiped out
> > > > the contents. Maybe having a skel file with just the headings and empty
> > > > headers wouldn't be such a bad idea after all.
> > > > 
> > > > I'm wondering if it belongs in the GLEP repo though. Maybe just
> > > > skel.rst? (given that www globs on glep-[0-9]...)
> > > > 
> > > 
> > > skel.rst would work I think; any file name that didn't disrupt
> > > automation would be good enough, though. No real preference.
> > > 
> > 
> > OTOH, I think we'll start by adding it to gentoo syntax packages for our
> > editors, so e.g. typing:
> > 
> > $ vim glep-0100.rst
> > 
> > you'd get the skel in place. I guess we'll see how good coverage that
> > has, and then decide if we need another skel in the repo.
> > 
> 
> Now that you mention it, putting it into syntax packages seems cleaner
> and editors could get automatic support. *And* this repository doesn't
> have to be touched...
> 
> Maybe we have a winner? :p

Nah, we just wait for someone to tell us that he has an editor without
proper syntax packages ;-).

-- 
Best regards,
Michał Górny

Re: [gentoo-project] [PATCH 13/18] glep-0001: Do not require a specific header order

[Michał Górny]

W dniu czw, 14.09.2017 o godzinie 21∶03 +0200, użytkownik Michał Górny
napisał:
> Most of the GLEPs never really followed the header order specified
> in GLEP 1, and there is no technical reason to enforce that.
> 

ulm has requested that we keep the requirement for header order, so I
withdraw this patch. Will submit a complete updated batch once I get
more feedback.

-- 
Best regards,
Michał Górny

Re: [gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Ulrich Mueller]

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

>>>>> On Fri, 15 Sep 2017, Michał Górny wrote:

> W dniu pią, 15.09.2017 o godzinie 00∶04 -0700, użytkownik Daniel
> Campbell napisał:
>> Now that you mention it, putting it into syntax packages seems
>> cleaner and editors could get automatic support. *And* this
>> repository doesn't have to be touched...
>>
>> Maybe we have a winner? :p

> Nah, we just wait for someone to tell us that he has an editor
> without proper syntax packages ;-).

Emacs supports RST out of the box too, and it is automatically enabled
if the file has an .rst or .rest suffix. (Obviously .txt is too
generic for that; it can be enabled manually with M-x rst-mode RET.)
If necessary, I could create a skeleton for GLEPs with pre-filled
header lines and section structure.

Looks like nano doesn't support RST syntax. It gets confused and
mistakes the file as Rust:

   $ grep syntax /usr/share/nano/rust.nanorc
   syntax "rust" "\.rs"

Ulrich

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

Re: [gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Alec Warner]

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

On Fri, Sep 15, 2017 at 2:54 AM, Michał Górny <mgorny@gentoo.org> wrote:

> W dniu czw, 14.09.2017 o godzinie 23∶45 -0700, użytkownik Daniel
> Campbell napisał:
> > On 09/14/2017 11:31 PM, Michał Górny wrote:
> > > W dniu czw, 14.09.2017 o godzinie 14∶58 -0700, użytkownik Daniel
> > > Campbell napisał:
> > > > If I had to find a nitpick, it's a minor feature request: can we get
> a
> > > > GLEP template file later on, to aid the initial drafting process? I
> > > > didn't see it in the repo.
> > >
> > > I see your point. I always took some random late GLEP and wiped out
> > > the contents. Maybe having a skel file with just the headings and empty
> > > headers wouldn't be such a bad idea after all.
> > >
> > > I'm wondering if it belongs in the GLEP repo though. Maybe just
> > > skel.rst? (given that www globs on glep-[0-9]...)
> > >
> >
> > skel.rst would work I think; any file name that didn't disrupt
> > automation would be good enough, though. No real preference.
> >
>
> OTOH, I think we'll start by adding it to gentoo syntax packages for our
> editors, so e.g. typing:
>
> $ vim glep-0100.rst
>
> you'd get the skel in place. I guess we'll see how good coverage that
> has, and then decide if we need another skel in the repo.
>

But what about people editing GLEPs on non-Gentoo machines? :)

-A


>
> --
> Best regards,
> Michał Górny
>
>
>

[-- Attachment #2: Type: text/html, Size: 2151 bytes --]

Re: [gentoo-project] [RFC] GLEP 1/2 updates for the new old-school GLEP workflow

[Michael Orlitzky]

> 
> But what about people editing GLEPs on non-Gentoo machines? :)
> 

https://wiki.gentoo.org/wiki/Project:Prefix

Re: [gentoo-project] [PATCH 03/18] glep-0001: Restore most of old GLEP headers

[Kristian Fiskerstrand]

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

On 09/14/2017 09:03 PM, Michał Górny wrote:
> +The Created header records the date that the GLEP was assigned a number, while
> +Post-History is used to record the dates of when new versions of the GLEP are
> +posted to gentoo-dev.  Both headers should be in dd-mmm-yyyy format, e.g.
> +14-Aug-2001.

I understand that this is in line with the historical values, but since
we're swithing things around again anyways, why are we not using ISO8601
format, YYYY-mm-dd, for all dates?

-- 
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-project] [PATCH 03/18] glep-0001: Restore most of old GLEP headers

[Kristian Fiskerstrand]

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

On 09/16/2017 03:34 PM, Kristian Fiskerstrand wrote:
> On 09/14/2017 09:03 PM, Michał Górny wrote:
>> +The Created header records the date that the GLEP was assigned a number, while
>> +Post-History is used to record the dates of when new versions of the GLEP are
>> +posted to gentoo-dev.  Both headers should be in dd-mmm-yyyy format, e.g.
>> +14-Aug-2001.
> 
> I understand that this is in line with the historical values, but since
> we're swithing things around again anyways, why are we not using ISO8601
> format, YYYY-mm-dd, for all dates?
> 

Nevermind, I see this is covered in [gentoo-project] [PATCH 07/18]
glep-0001: Replace dates with ISO 8601 :)

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