[gentoo-dev] [PATCH 1/2] glep-0042: Drop requirement for detached signatures.

[gentoo-dev] [PATCH 1/2] glep-0042: Drop requirement for detached signatures.

[Ulrich Müller]

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

---
 glep-0042.rst | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/glep-0042.rst b/glep-0042.rst
index c6b41e9..7726ea4 100644
--- a/glep-0042.rst
+++ b/glep-0042.rst
@@ -9,7 +9,7 @@ Type: Standards Track
 Status: Final
 Version: 3
 Created: 2005-10-31
-Last-Modified: 2016-03-18
+Last-Modified: 2017-11-26
 Post-History: 2005-11-01, 2005-11-05, 2005-11-07, 2005-12-11, 2005-12-13,
               2005-12-18, 2006-01-05, 2006-03-02, 2006-03-06, 2006-06-12,
               2006-09-05, 2016-03-10
@@ -203,19 +203,16 @@ A news item file is a text file, encoded using UTF-8 [#rfc-3629]_ for
 compatibility with and for the same reasons as existing Gentoo documentation
 [#docs-policy]_ and the tree [#glep-31]_.
 
-News items must be signed with a detached GPG signature.::
-
-    gpg --armour --detach-sign ????-??-??-*.??.txt
-
-This GLEP does not specify the type or strength of signature to be used, nor
-does it discuss how, if at all, a centralised keychain will be provided. These
-issues should be handled as part of the signing policy discussions.
-
 A news item file's content will consist of an RFC 822 style header [#rfc-822]_
 followed by the main body of the message as plain text. This GLEP defines
 various optional and mandatory headers. Future GLEPs may propose new headers —
 tools handling these news items must ignore any unrecognised header.
 
+.. Note:: A previous version of this GLEP had required that news items must
+   be signed with a detached OpenPGP signature. This was no longer deemed
+   necessary after moving news items to a Git repository with commit signing,
+   and deployment of full-tree verification per GLEP 74 [#glep-74]_.
+
 News Item Headers
 '''''''''''''''''
 
@@ -500,6 +497,9 @@ References
      https://www.gentoo.org/glep/glep-0034.html
 .. [#glep-45] GLEP 45: "GLEP date format", Henrik Brix Andersen,
      https://www.gentoo.org/glep/glep-0045.html
+.. [#glep-74] GLEP 74: "Full-tree verification using Manifest files",
+     Michał Górny, Robin Hugh Johnson, Ulrich Müller,
+     https://www.gentoo.org/glep/glep-0074.html
 .. [#iso-639] ISO 639 "Code for the representation of names of languages"
 .. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance
      Albertson,
-- 
2.15.0

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

[gentoo-dev] [PATCH 2/2] glep-0042: Update and clarify naming rules.

[Ulrich Müller]

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

Update the GLEP from ISO 639 to IETF language tags (BCP 47), in order
to make it consistent with usage in the L10N USE_EXPAND variable.
This will make no difference for most common languages. Also there are
currently no translations of news items at all.

Add a note clarifying what "very short" means.
---
 glep-0042.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/glep-0042.rst b/glep-0042.rst
index 7726ea4..90ae0b2 100644
--- a/glep-0042.rst
+++ b/glep-0042.rst
@@ -179,7 +179,9 @@ form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``),
 ``mm`` is the month (``01`` through ``12``) and dd is the day of the month
 (``01`` through ``31``). The ``short-name`` is a very short name describing the
 news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``,
-``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore).
+``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore). While there
+is no hard restriction for the length of ``short-name``, it is strongly
+recommended to limit it to at most 20 characters.
 
 News Item Directories
 ---------------------
@@ -191,8 +193,8 @@ The directory will contain a file named ``yyyy-mm-dd-short-name.en.txt``, which
 contains the text of the news item, in English, in the format described below.
 
 If a news item is translated, other files named ``yyyy-mm-dd-short-name.xx.txt``
-(where ``xx`` is the ISO 639 [#iso-639]_ two letter language code, and the date
-remains the same as the original news item) will also be provided. However, only
+(where ``xx`` is a valid IETF language tag [#bcp-47]_, and the date remains
+the same as the original news item) will also be provided. However, only
 the English version of a news item is authoritative.  This anglocentricity is
 justified by precedent [#glep-34]_.
 
@@ -475,6 +477,8 @@ Example Files
 References
 ==========
 
+.. [#bcp-47] BCP 47: "Tags for identifying languages",
+     https://tools.ietf.org/rfc/bcp/bcp47.txt
 .. [#bug-11359] Bugzilla Bug 11359
    "[NEW FEATURE] pkg_postinst/pkg_preinst ewarn/einfo logging",
    https://bugs.gentoo.org/show_bug.cgi?id=11359
@@ -500,7 +504,6 @@ References
 .. [#glep-74] GLEP 74: "Full-tree verification using Manifest files",
      Michał Górny, Robin Hugh Johnson, Ulrich Müller,
      https://www.gentoo.org/glep/glep-0074.html
-.. [#iso-639] ISO 639 "Code for the representation of names of languages"
 .. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance
      Albertson,
      https://archives.gentoo.org/gentoo-dev/message/4204839d4091758c3bad1dbd18ed16f7
-- 
2.15.0

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

[gentoo-dev] [PATCH 0/2] Two updates for GLEP 42

[Ulrich Müller]

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

Here are two updates for GLEP 42, for review.

Currently it is required that every news item is accompanied by a
detached OpenPGP signature. To my knowledge, verification of these
signatures was never implemented. With Git commit signing and after
full-tree verification is implemented, these detached signatures will
become fully redundant. In addition, we noticed that several of the
signatures have a bad format (e.g., are not detached signatures
at all). Therefore the first patch drops the requirement for detached
OpenPGP signatures.

The second patch updates the GLEP from ISO 639 to IETF language codes
(BCP 47), in order to make it consistent with usage in the L10N
USE_EXPAND variable. This will make no difference for most common
languages. Please note that a BCP 47 language tag can in principle
be longer than two letters, and can contain characters [A-Za-z0-9-].
(Since there are currently no translations of news items, all this is
rather academic, though.)

Finally (also in the second patch) a note is added clarifying what
"very short" means in a filename context. Technically, the short-name
is needed only to distinguish between multiple news items posted at
the same day. However, there seems to be a tendency to repeat half
of the news item's content in its filename. ;-)

Ulrich Müller (2):
  glep-0042: Drop requirement for detached signatures.
  glep-0042: Update and clarify naming rules.

 glep-0042.rst | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

-- 
2.15.0

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

[gentoo-dev] Re: [PATCH 2/2] glep-0042: Update and clarify naming rules.

[Duncan]

Ulrich Müller posted on Mon, 27 Nov 2017 00:30:49 +0100 as excerpted:

> diff --git a/glep-0042.rst b/glep-0042.rst
> index 7726ea4..90ae0b2 100644
> --- a/glep-0042.rst
> +++ b/glep-0042.rst
> @@ -179,7 +179,9 @@ form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``),
>  ``mm`` is the month (``01`` through ``12``) and dd is the day of the month
>  (``01`` through ``31``). The ``short-name`` is a very short name describing the
>  news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``,
> -``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore).
> +``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore). While there
> +is no hard restriction for the length of ``short-name``, it is strongly
> +recommended to limit it to at most 20 characters.

Arguably bikeshedding but changing up the last sentence to read a bit smoother
(I skipped formatting)...

While there is no hard restriction on the length of short-name,
limiting it to 20 characters is strongly recommended.

(s/for/on/, reversing order of the limit and strongly recommended.)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [gentoo-dev] Re: [PATCH 2/2] glep-0042: Update and clarify naming rules.

[Aaron W. Swenson]

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

On 2017-11-27 10:54, Duncan wrote:
> Ulrich Müller posted on Mon, 27 Nov 2017 00:30:49 +0100 as excerpted:
> 
> > diff --git a/glep-0042.rst b/glep-0042.rst
> > index 7726ea4..90ae0b2 100644
> > --- a/glep-0042.rst
> > +++ b/glep-0042.rst
> > @@ -179,7 +179,9 @@ form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``),
> >  ``mm`` is the month (``01`` through ``12``) and dd is the day of the month
> >  (``01`` through ``31``). The ``short-name`` is a very short name describing the
> >  news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``,
> > -``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore).
> > +``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore). While there
> > +is no hard restriction for the length of ``short-name``, it is strongly
> > +recommended to limit it to at most 20 characters.
> 
> Arguably bikeshedding but changing up the last sentence to read a bit smoother
> (I skipped formatting)...
> 
> While there is no hard restriction on the length of short-name,
> limiting it to 20 characters is strongly recommended.
> 
> (s/for/on/, reversing order of the limit and strongly recommended.)

I agree. This one reads a bit better.

Does it matter if people notice the recommendation? Should it be its own
paragraph for emphasis?

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

Re: [gentoo-dev] [PATCH 1/2] glep-0042: Drop requirement for detached signatures.

[Aaron W. Swenson]

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

On 2017-11-27 00:13, Ulrich Müller wrote:
> …
> +.. Note:: A previous version of this GLEP had required that news items must
> +   be signed with a detached OpenPGP signature. This was no longer deemed
> +   necessary after moving news items to a Git repository with commit signing,
> +   and deployment of full-tree verification per GLEP 74 [#glep-74]_.

This was deemed no longer necessary…

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

[gentoo-dev] Re: [PATCH 2/2] glep-0042: Update and clarify naming rules.

[Ulrich Mueller]

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

>>>>> On Mon, 27 Nov 2017, Duncan  wrote:

> Arguably bikeshedding but changing up the last sentence to read a
> bit smoother (I skipped formatting)...

> While there is no hard restriction on the length of short-name,
> limiting it to 20 characters is strongly recommended.

> (s/for/on/, reversing order of the limit and strongly recommended.)

Applied, thanks.

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

Re: [gentoo-dev] Re: [PATCH 2/2] glep-0042: Update and clarify naming rules.

[Ulrich Mueller]

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

>>>>> On Mon, 27 Nov 2017, Aaron W Swenson wrote:

> On 2017-11-27 10:54, Duncan wrote:
>> While there is no hard restriction on the length of short-name,
>> limiting it to 20 characters is strongly recommended.
>> 
>> [...]

> Does it matter if people notice the recommendation? Should it be its
> own paragraph for emphasis?

I guess that the devmanual section will be read more often, so I'll
prepare a patch for it when (and if) the GLEP changes are accepted:
https://devmanual.gentoo.org/general-concepts/news/index.html

That it currently has just "name" rather than "very short name" (as in
the GLEP) doesn't help, I suppose.

Ulrich

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

Re: [gentoo-dev] [PATCH 1/2] glep-0042: Drop requirement for detached signatures.

[Ulrich Mueller]

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

>>>>> On Mon, 27 Nov 2017, Aaron W Swenson wrote:

> This was deemed no longer necessary…

Applied, thanks.

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

[gentoo-dev] [PATCH v2] GLEP 42 update

[Ulrich Mueller]

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

>>>>> On Mon, 27 Nov 2017, Ulrich Müller wrote:

> Currently it is required that every news item is accompanied by a
> detached OpenPGP signature. To my knowledge, verification of these
> signatures was never implemented. With Git commit signing and after
> full-tree verification is implemented, these detached signatures
> will become fully redundant. In addition, we noticed that several of
> the signatures have a bad format (e.g., are not detached signatures
> at all). Therefore the first patch drops the requirement for
> detached OpenPGP signatures.

> The second patch updates the GLEP from ISO 639 to IETF language
> codes (BCP 47), in order to make it consistent with usage in the
> L10N USE_EXPAND variable. This will make no difference for most
> common languages. Please note that a BCP 47 language tag can in
> principle be longer than two letters, and can contain characters
> [A-Za-z0-9-]. (Since there are currently no translations of news
> items, all this is rather academic, though.)

> Finally (also in the second patch) a note is added clarifying
> what "very short" means in a filename context. Technically, the
> short-name is needed only to distinguish between multiple news
> items posted at the same day. However, there seems to be a tendency
> to repeat half of the news item's content in its filename. ;-)

Updated version below (as a single patch), including corrections from
mailing list and IRC. If there are no further comments, I plan to
submit this for approval in the next Council meeting.

Full commit log: https://gitweb.gentoo.org/data/glep.git/log/?h=glep42-update
Rendered version: https://dev.gentoo.org/~ulm/scratch/glep-0042.html

Ulrich


diff --git a/glep-0042.rst b/glep-0042.rst
index c6b41e9..416bd18 100644
--- a/glep-0042.rst
+++ b/glep-0042.rst
@@ -7,12 +7,12 @@ Author: Ciaran McCreesh <ciaranm@gentoo.org>,
         Ulrich Müller <ulm@gentoo.org>
 Type: Standards Track
 Status: Final
-Version: 3
+Version: 4
 Created: 2005-10-31
-Last-Modified: 2016-03-18
+Last-Modified: 2017-11-29
 Post-History: 2005-11-01, 2005-11-05, 2005-11-07, 2005-12-11, 2005-12-13,
               2005-12-18, 2006-01-05, 2006-03-02, 2006-03-06, 2006-06-12,
-              2006-09-05, 2016-03-10
+              2006-09-05, 2016-03-10, 2017-11-27
 Content-Type: text/x-rst
 ---
 
@@ -179,7 +179,9 @@ form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``),
 ``mm`` is the month (``01`` through ``12``) and dd is the day of the month
 (``01`` through ``31``). The ``short-name`` is a very short name describing the
 news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``,
-``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore).
+``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore). While there is no
+hard restriction on the length of ``short-name``, limiting it to 20 characters
+is strongly recommended.
 
 News Item Directories
 ---------------------
@@ -190,9 +192,9 @@ news item's identifier.
 The directory will contain a file named ``yyyy-mm-dd-short-name.en.txt``, which
 contains the text of the news item, in English, in the format described below.
 
-If a news item is translated, other files named ``yyyy-mm-dd-short-name.xx.txt``
-(where ``xx`` is the ISO 639 [#iso-639]_ two letter language code, and the date
-remains the same as the original news item) will also be provided. However, only
+Any translations of a news item will be provided in additional files. Their
+name ``yyyy-mm-dd-short-name.lang.txt`` is obtained from the original filename
+by replacing ``en`` with another IETF language tag [#bcp-47]_. However, only
 the English version of a news item is authoritative.  This anglocentricity is
 justified by precedent [#glep-34]_.
 
@@ -203,19 +205,16 @@ A news item file is a text file, encoded using UTF-8 [#rfc-3629]_ for
 compatibility with and for the same reasons as existing Gentoo documentation
 [#docs-policy]_ and the tree [#glep-31]_.
 
-News items must be signed with a detached GPG signature.::
-
-    gpg --armour --detach-sign ????-??-??-*.??.txt
-
-This GLEP does not specify the type or strength of signature to be used, nor
-does it discuss how, if at all, a centralised keychain will be provided. These
-issues should be handled as part of the signing policy discussions.
-
 A news item file's content will consist of an RFC 822 style header [#rfc-822]_
 followed by the main body of the message as plain text. This GLEP defines
 various optional and mandatory headers. Future GLEPs may propose new headers —
 tools handling these news items must ignore any unrecognised header.
 
+.. Note:: A previous version of this GLEP had required that news items must
+   be signed with a detached OpenPGP signature. This was deemed no longer
+   necessary after moving news items to a Git repository with commit signing,
+   and deployment of full-tree verification per GLEP 74 [#glep-74]_.
+
 News Item Headers
 '''''''''''''''''
 
@@ -478,6 +477,8 @@ Example Files
 References
 ==========
 
+.. [#bcp-47] BCP 47: "Tags for identifying languages",
+     https://tools.ietf.org/rfc/bcp/bcp47.txt
 .. [#bug-11359] Bugzilla Bug 11359
    "[NEW FEATURE] pkg_postinst/pkg_preinst ewarn/einfo logging",
    https://bugs.gentoo.org/show_bug.cgi?id=11359
@@ -500,7 +501,9 @@ References
      https://www.gentoo.org/glep/glep-0034.html
 .. [#glep-45] GLEP 45: "GLEP date format", Henrik Brix Andersen,
      https://www.gentoo.org/glep/glep-0045.html
-.. [#iso-639] ISO 639 "Code for the representation of names of languages"
+.. [#glep-74] GLEP 74: "Full-tree verification using Manifest files",
+     Michał Górny, Robin Hugh Johnson, Ulrich Müller,
+     https://www.gentoo.org/glep/glep-0074.html
 .. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance
      Albertson,
      https://archives.gentoo.org/gentoo-dev/message/4204839d4091758c3bad1dbd18ed16f7

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