1. Forum
  2. Usenet
  3. LINUX.GENTOO.DEV

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

    From =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?@21:1/5 to All on Thu Sep 8 10:40:02 2022
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?@21:1/5 to All on Thu Sep 8 10:40:02 2022
    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-
  • From =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?@21:1/5 to All on Thu Sep 8 10:40:02 2022
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?@21:1/5 to All on Thu Sep 8 10:40:02 2022
    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.


    Man
  • From =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?@21:1/5 to All on Thu Sep 8 10:40:02 2022
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Ulrich Mueller@21:1/5 to All on Thu Sep 8 11:50:01 2022
    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/

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Ulrich Mueller@21:1/5 to All on Thu Sep 8 11:50:01 2022
    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.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Ulrich Mueller@21:1/5 to All on Thu Sep 8 11:50:01 2022
    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)

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?@21:1/5 to All on Thu Sep 8 13:20:01 2022
    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

    --- SoupGate-Win32 v1.05
    * O
  • From =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?@21:1/5 to All on Thu Sep 8 13:20:01 2022
    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
  • From =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?@21:1/5 to All on Thu Sep 8 13:20:01 2022
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?@21:1/5 to All on Thu Sep 8 13:20:01 2022
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?@21:1/5 to All on Thu Sep 8 13:20:01 2022
    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)
    +
    .. [#UNICO