[gentoo-dev] [PATCH 0/4] glep-0074: Clarifications

[gentoo-dev] [PATCH 0/4] glep-0074: Clarifications

[Michał Górny]

Hi,

Here are a few clarifications for the Manifest format specification
in GLEP 74.  They are mostly editorial changes, except for the last
patch.  The patches do, in order:

1. Replace bare "OpenPGP" with a reference to RFC 4880.

2. Make it clear that Manifests do not specify an entry for the
   top-level Manifest, nor IGNORE it explicitly.

3. Shortly describe the actual format used for Manifest entries rather
   than relying on GLEP 44 to do that, especially that it doesn't
   really.

4. Specify that Unix newline convention is to be used for Manifest
   files and spurious whitespace (including stray CRs) should be
   ignored.

Please review.


Michał Górny (4):
  glep-0074: Link OpenPGP to RFC 4880
  glep-0074: Clearly indicate that top-level Manifest is not listed
  glep-0074: Inline Manifest format description
  glep-0074: Specify newline convention

 glep-0074.rst | 38 +++++++++++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 7 deletions(-)

-- 
2.37.3

[gentoo-dev] [PATCH 1/4] glep-0074: Link OpenPGP to RFC 4880

[Michał Górny]

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 glep-0074.rst | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/glep-0074.rst b/glep-0074.rst
index 4adf068..80a63a1 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -8,8 +8,8 @@ Type: Standards Track
 Status: Final
 Version: 1.1
 Created: 2017-10-21
-Last-Modified: 2018-03-11
-Post-History: 2017-10-26, 2017-11-16, 2018-02-08
+Last-Modified: 2022-09-08
+Post-History: 2017-10-26, 2017-11-16, 2018-02-08, 2022-09-08
 Content-Type: text/x-rst
 Requires: 59, 61
 Replaces: 44, 58, 60
@@ -82,7 +82,8 @@ Manifest file locations and nesting
 The ``Manifest`` file located in the root directory of the repository
 is called top-level Manifest, and it is used to perform the full-tree
 verification. In order to verify the authenticity, it must be signed
-using OpenPGP, using the armored cleartext format.
+using OpenPGP, using the armored cleartext format as defined by RFC 4880
+§ 7 or a subsequent standard [#RFC4880]_.
 
 The top-level Manifest may reference sub-Manifests contained
 in subdirectories of the repository. The sub-Manifests are traditionally
@@ -1026,6 +1027,9 @@ References
 .. [#GLEP61] GLEP 61: Manifest2 compression
    (https://www.gentoo.org/glep/glep-0061.html)
 
+.. [#RFC4880] RFC 4880: OpenPGP Message Format
+   (https://www.rfc-editor.org/rfc/rfc4880)
+
 .. [#UNICODE] The Unicode standard
    (https://unicode.org/versions/latest/)
 
-- 
2.37.3

[gentoo-dev] [PATCH 2/4] glep-0074: Clearly indicate that top-level Manifest is not listed

[Michał Górny]

Make it clear that the top-level Manifest is not verified through itself
or other Manifests, and should not be explicitly listed in IGNORE.

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 glep-0074.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/glep-0074.rst b/glep-0074.rst
index 80a63a1..0117c4b 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -109,8 +109,9 @@ of specific files and directories (recursively):
 
 3. using names starting with a dot (``.``) which are always skipped.
 
-All files that are not ignored must be covered by at least one
-of the Manifests.
+The top-level Manifest is skipped implicitly and it is an error to list
+it in Manifest files. All the remaining files that are not ignored must
+be covered by at least one of the Manifests.
 
 A single file may be matched by multiple identical or equivalent
 Manifest entries, if and only if the entries have the same semantics,
-- 
2.37.3

[gentoo-dev] [PATCH 3/4] glep-0074: Inline Manifest format description

[Michał Górny]

Rather than limiting the GLEP to list changes from GLEP 44, include
a short inline explanation of the base Manifest format.  This makes
the standard more standalone, and GLEP 44 did not do a very good job
of describing the format either.

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 glep-0074.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/glep-0074.rst b/glep-0074.rst
index 0117c4b..ff8002f 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -68,6 +68,12 @@ repurposed as a generic *tag* that could also indicate additional
 (non-checksum) metadata. Appropriately, those tags can be followed by
 other space-separated values.
 
+The Manifest file is a line-oriented text file. Every line comprises
+a single Manifest entry and consists of one or more fields separated
+by a single space character (``U+0020``). The tags and their
+corresponding fields are defined in the `modern Manifest tags`_
+and `deprecated Manifest tags`_ sections.
+
 Unless specified otherwise, the paths used in the Manifest files
 are relative to the directory containing the Manifest file. The paths
 must not reference the parent directory (``..``). Forward slash (``/``)
-- 
2.37.3

[gentoo-dev] [PATCH 4/4] glep-0074: Specify newline convention

[Michał Górny]

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 glep-0074.rst | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/glep-0074.rst b/glep-0074.rst
index ff8002f..a65a7e7 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -6,7 +6,7 @@ Author: Michał Górny <mgorny@gentoo.org>,
         Ulrich Müller <ulm@gentoo.org>
 Type: Standards Track
 Status: Final
-Version: 1.1
+Version: 1.2
 Created: 2017-10-21
 Last-Modified: 2022-09-08
 Post-History: 2017-10-26, 2017-11-16, 2018-02-08, 2022-09-08
@@ -79,7 +79,10 @@ are relative to the directory containing the Manifest file. The paths
 must not reference the parent directory (``..``). Forward slash (``/``)
 is used as path component separator.
 
-The Manifest files use UTF-8 encoding.
+The Manifest files use UTF-8 encoding.  Line feed (``U+000A``) character
+is used to separate lines.  For best compatibility, empty lines and any
+additional whitespace, including the carriage return character
+(``U+000D``) should be ignored by the implementation.
 
 
 Manifest file locations and nesting
@@ -516,6 +519,16 @@ information to perform the verification following all the rules specific
 to the Gentoo repository.
 
 
+Newline convention
+------------------
+Prior to version 1.2, the specification did not indicate the encoding
+to be used for newlines. Since the format is primarily used on Gentoo
+Linux systems, this has been changed to follow the Unix convention
+of using the line feed character. However, for best interoperability
+implementation should be prepared to treat superfluous carriage return
+characters as whitespace and ignore them.
+
+
 Tree design
 -----------
 
-- 
2.37.3

Re: [gentoo-dev] [PATCH 2/4] glep-0074: Clearly indicate that top-level Manifest is not listed

[Ulrich Mueller]

>>>>> On Thu, 08 Sep 2022, Michał Górny wrote:
 
> -All files that are not ignored must be covered by at least one
> -of the Manifests.
> +The top-level Manifest is skipped implicitly and it is an error to list
> +it in Manifest files. All the remaining files that are not ignored must
> +be covered by at least one of the Manifests.

Suggestion: s/the remaining files/remaining files/ 

Re: [gentoo-dev] [PATCH 4/4] glep-0074: Specify newline convention

[Ulrich Mueller]

>>>>> On Thu, 08 Sep 2022, Michał Górny wrote:
 
> -The Manifest files use UTF-8 encoding.
> +The Manifest files use UTF-8 encoding.  Line feed (``U+000A``) character
> +is used to separate lines.  For best compatibility, empty lines and any
> +additional whitespace, including the carriage return character
> +(``U+000D``) should be ignored by the implementation.

Either "Line feed (``U+000A``) is used ..." or "The line feed
(``U+000A``) character is used ..."

> +Newline convention
> +------------------

Please insert a blank line here.

> +Prior to version 1.2, the specification did not indicate the encoding
> +to be used for newlines. Since the format is primarily used on Gentoo
> +Linux systems, this has been changed to follow the Unix convention
> +of using the line feed character. However, for best interoperability
> +implementation should be prepared to treat superfluous carriage return

s/implementation/the implementation/

> +characters as whitespace and ignore them.

Also I notice that you use double space after full stop in the first
paragraph above but a single space in the second paragraph. This should
be consistent throughout the GLEP.

Re: [gentoo-dev] [PATCH 0/4] glep-0074: Clarifications

[Ulrich Mueller]

Please also update the license of the GLEP to CC-BY-SA-4.0 [1].

[1] https://www.gentoo.org/glep/glep-0001.html#what-belongs-in-a-successful-glep
    (item 8)

[gentoo-dev] [PATCH v2 1/5] glep-0074: Update license to CC BY-SA 4.0

[Michał Górny]

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 glep-0074.rst | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/glep-0074.rst b/glep-0074.rst
index 4adf068..b61801d 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -8,8 +8,8 @@ Type: Standards Track
 Status: Final
 Version: 1.1
 Created: 2017-10-21
-Last-Modified: 2018-03-11
-Post-History: 2017-10-26, 2017-11-16, 2018-02-08
+Last-Modified: 2022-09-08
+Post-History: 2017-10-26, 2017-11-16, 2018-02-08, 2022-09-08
 Content-Type: text/x-rst
 Requires: 59, 61
 Replaces: 44, 58, 60
@@ -1071,6 +1071,7 @@ References
 
 Copyright
 =========
-This work is licensed under the Creative Commons Attribution-ShareAlike 3.0
-Unported License. To view a copy of this license, visit
-https://creativecommons.org/licenses/by-sa/3.0/.
+
+This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+International License. To view a copy of this license, visit
+https://creativecommons.org/licenses/by-sa/4.0/.
-- 
2.37.3

[gentoo-dev] [PATCH v2 2/5] glep-0074: Link OpenPGP to RFC 4880

[Michał Górny]

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 glep-0074.rst | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/glep-0074.rst b/glep-0074.rst
index b61801d..1005f85 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -82,7 +82,8 @@ Manifest file locations and nesting
 The ``Manifest`` file located in the root directory of the repository
 is called top-level Manifest, and it is used to perform the full-tree
 verification. In order to verify the authenticity, it must be signed
-using OpenPGP, using the armored cleartext format.
+using OpenPGP, using the armored cleartext format as defined by RFC 4880
+§ 7 or a subsequent standard [#RFC4880]_.
 
 The top-level Manifest may reference sub-Manifests contained
 in subdirectories of the repository. The sub-Manifests are traditionally
@@ -1026,6 +1027,9 @@ References
 .. [#GLEP61] GLEP 61: Manifest2 compression
    (https://www.gentoo.org/glep/glep-0061.html)
 
+.. [#RFC4880] RFC 4880: OpenPGP Message Format
+   (https://www.rfc-editor.org/rfc/rfc4880)
+
 .. [#UNICODE] The Unicode standard
    (https://unicode.org/versions/latest/)
 
-- 
2.37.3

[gentoo-dev] [PATCH v2 3/5] glep-0074: Clearly indicate that top-level Manifest is not listed

[Michał Górny]

Make it clear that the top-level Manifest is not verified through itself
or other Manifests, and should not be explicitly listed in IGNORE.

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 glep-0074.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/glep-0074.rst b/glep-0074.rst
index 1005f85..0ce7baf 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -109,8 +109,9 @@ of specific files and directories (recursively):
 
 3. using names starting with a dot (``.``) which are always skipped.
 
-All files that are not ignored must be covered by at least one
-of the Manifests.
+The top-level Manifest is skipped implicitly and it is an error to list
+it in Manifest files. All remaining files that are not ignored must
+be covered by at least one of the Manifests.
 
 A single file may be matched by multiple identical or equivalent
 Manifest entries, if and only if the entries have the same semantics,
-- 
2.37.3

[gentoo-dev] [PATCH v2 4/5] glep-0074: Inline Manifest format description

[Michał Górny]

Rather than limiting the GLEP to list changes from GLEP 44, include
a short inline explanation of the base Manifest format.  This makes
the standard more standalone, and GLEP 44 did not do a very good job
of describing the format either.

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 glep-0074.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/glep-0074.rst b/glep-0074.rst
index 0ce7baf..677bf35 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -68,6 +68,12 @@ repurposed as a generic *tag* that could also indicate additional
 (non-checksum) metadata. Appropriately, those tags can be followed by
 other space-separated values.
 
+The Manifest file is a line-oriented text file. Every line comprises
+a single Manifest entry and consists of one or more fields separated
+by a single space character (``U+0020``). The tags and their
+corresponding fields are defined in the `modern Manifest tags`_
+and `deprecated Manifest tags`_ sections.
+
 Unless specified otherwise, the paths used in the Manifest files
 are relative to the directory containing the Manifest file. The paths
 must not reference the parent directory (``..``). Forward slash (``/``)
-- 
2.37.3

[gentoo-dev] [PATCH v2 5/5] glep-0074: Specify newline convention

[Michał Górny]

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 glep-0074.rst | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/glep-0074.rst b/glep-0074.rst
index 677bf35..182a871 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -6,7 +6,7 @@ Author: Michał Górny <mgorny@gentoo.org>,
         Ulrich Müller <ulm@gentoo.org>
 Type: Standards Track
 Status: Final
-Version: 1.1
+Version: 1.2
 Created: 2017-10-21
 Last-Modified: 2022-09-08
 Post-History: 2017-10-26, 2017-11-16, 2018-02-08, 2022-09-08
@@ -79,7 +79,10 @@ are relative to the directory containing the Manifest file. The paths
 must not reference the parent directory (``..``). Forward slash (``/``)
 is used as path component separator.
 
-The Manifest files use UTF-8 encoding.
+The Manifest files use UTF-8 encoding. Line feed (``U+000A``) is used
+to separate lines. For best compatibility, empty lines and any
+additional whitespace, including the carriage return character
+(``U+000D``) should be ignored by the implementation.
 
 
 Manifest file locations and nesting
@@ -516,6 +519,17 @@ information to perform the verification following all the rules specific
 to the Gentoo repository.
 
 
+Newline convention
+------------------
+
+Prior to version 1.2, the specification did not indicate the encoding
+to be used for newlines. Since the format is primarily used on Gentoo
+Linux systems, this has been changed to follow the Unix convention
+of using the line feed character. However, for best interoperability
+the implementation should be prepared to treat superfluous carriage
+return characters as whitespace and ignore them.
+
+
 Tree design
 -----------
 
-- 
2.37.3