[gentoo-dev] [PATCH 0/3] glep-0074: clarifications about size and checksum fields

[gentoo-dev] [PATCH 0/3] glep-0074: clarifications about size and checksum fields

[Michał Górny]

Hi,

Here's next part of GLEP 74 updates, this time I think it qualifiers
as 100% editorial.  Ulrich Müller noticed that we don't specify how
to express sizes and checksums.  I've partially solved the latter while
adding the hash algorithm table and these patches should clarify
the matters even further.

Notably, they:

1) clarify that DIST entries are relevant to package managers only

2) specify that size is an unsigned decimal, and checksums consist
   of name-value pairs

3) clarify that 'Hex' encoding of hashes means lowercase hex without
   any prefix or suffix

Perhaps the most controversial part is requiring lowercase -- but
(drumroll...) Portage reports hash mismatch if you use uppercase.


Michał Górny (3):
  glep-0074: Clarify that DIST entries are specific to PMs
  glep-0074: Specify the format of size and checksum fields
  glep-0074: Clarify the hex encoding of hash values

 glep-0074.rst | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

-- 
2.37.3

[gentoo-dev] [PATCH 1/3] glep-0074: Clarify that DIST entries are specific to PMs

[Michał Górny]

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

diff --git a/glep-0074.rst b/glep-0074.rst
index 7f53302..54bf216 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -8,7 +8,7 @@ Type: Standards Track
 Status: Final
 Version: 1.3
 Created: 2017-10-21
-Last-Modified: 2022-09-21
+Last-Modified: 2022-09-23
 Post-History: 2017-10-26, 2017-11-16, 2018-02-08, 2022-09-08, 2022-09-11
 Content-Type: text/x-rst
 Requires: 59, 61
@@ -286,6 +286,9 @@ The Manifest files can specify the following tags:
   ``DIST`` entries apply to all packages below the Manifest file
   specifying them.
 
+  This entry is specific to package manager use and it is not used
+  when verifying local directories.
+
 
 Deprecated Manifest tags
 ------------------------
-- 
2.37.3

[gentoo-dev] [PATCH 2/3] glep-0074: Specify the format of size and checksum fields

[Michał Górny]

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

diff --git a/glep-0074.rst b/glep-0074.rst
index 54bf216..bfbe092 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -191,6 +191,19 @@ The encoding can be used for other characters as well. In particular,
 escaping non-printable characters might be desirable.
 
 
+Size and checksum fields
+------------------------
+
+The Manifest entries used to describe files list the file size and one
+or more checksums. The size is expressed as an unsigned decimal integer.
+The checksums are expressed using pairs of fields, with the first field
+in every pair specifying the hash name and the second field its value.
+The names of hashes and the encoding of their values are specified
+in the `checksum algorithms`_ section.
+
+It is invalid to specify a hash name without a value.
+
+
 File verification
 -----------------
 
-- 
2.37.3

[gentoo-dev] [PATCH 3/3] glep-0074: Clarify the hex encoding of hash values

[Michał Górny]

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

diff --git a/glep-0074.rst b/glep-0074.rst
index bfbe092..7594932 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -418,6 +418,14 @@ Checksum algorithms
    | ``WHIRLPOOL``   | Whirlpool [#BARRETO]_ | 512  | Hex  |             |
    +-----------------+-----------------------+------+------+-------------+
 
+The following hash value encodings are used:
+
+Hex
+  The hash value expressed as an unsigned hexadecimal integer,
+  using digits ``0`` to ``9`` and lowercase letters ``a`` to ``f``,
+  with no prefix or suffix.
+
+
 Any new hashes must be added to this specification prior to being used
 in Manifest files. Adding a new hash is considered
 a backwards-compatible change to the GLEP. It is recommended that new
-- 
2.37.3

Re: [gentoo-dev] [PATCH 0/3] glep-0074: clarifications about size and checksum fields

[Sheng Yu]

Hi,

The hash does not need to be lowercase. It can be a quick fix in portage to accept any case.

Thanks,
Sheng Yu


------- Original Message -------
On Friday, September 23rd, 2022 at 10:03, Michał Górny <mgorny@gentoo.org> wrote:


> 
> 
> Hi,
> 
> Here's next part of GLEP 74 updates, this time I think it qualifiers
> as 100% editorial. Ulrich Müller noticed that we don't specify how
> to express sizes and checksums. I've partially solved the latter while
> adding the hash algorithm table and these patches should clarify
> the matters even further.
> 
> Notably, they:
> 
> 1) clarify that DIST entries are relevant to package managers only
> 
> 2) specify that size is an unsigned decimal, and checksums consist
> of name-value pairs
> 
> 3) clarify that 'Hex' encoding of hashes means lowercase hex without
> any prefix or suffix
> 
> Perhaps the most controversial part is requiring lowercase -- but
> (drumroll...) Portage reports hash mismatch if you use uppercase.
> 
> 
> Michał Górny (3):
> glep-0074: Clarify that DIST entries are specific to PMs
> glep-0074: Specify the format of size and checksum fields
> glep-0074: Clarify the hex encoding of hash values
> 
> glep-0074.rst | 26 +++++++++++++++++++++++++-
> 1 file changed, 25 insertions(+), 1 deletion(-)
> 
> --
> 2.37.3

Re: [gentoo-dev] [PATCH 0/3] glep-0074: clarifications about size and checksum fields

[Ulrich Mueller]

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

>>>>> On Fri, 23 Sep 2022, Sheng Yu wrote:

> The hash does not need to be lowercase. It can be a quick fix in
> portage to accept any case.

That would break backwards compatibility. Also, having a uniquely
defined format helps when comparing hashes with the output of tools like
b2sum or sha512sum.

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] [PATCH 2/3] glep-0074: Specify the format of size and checksum fields

[John Helmert III]

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

On Fri, Sep 23, 2022 at 04:03:54PM +0200, Michał Górny wrote:
> Signed-off-by: Michał Górny <mgorny@gentoo.org>
> ---
>  glep-0074.rst | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/glep-0074.rst b/glep-0074.rst
> index 54bf216..bfbe092 100644
> --- a/glep-0074.rst
> +++ b/glep-0074.rst
> @@ -191,6 +191,19 @@ The encoding can be used for other characters as well. In particular,
>  escaping non-printable characters might be desirable.
>  
>  
> +Size and checksum fields
> +------------------------
> +
> +The Manifest entries used to describe files list the file size and one
> +or more checksums. The size is expressed as an unsigned decimal integer.

"an unsigned decimal integer" representing the file's size in bytes
(rather than bits, or nibbles, or $UNIT), right?

> +The checksums are expressed using pairs of fields, with the first field
> +in every pair specifying the hash name and the second field its value.
> +The names of hashes and the encoding of their values are specified
> +in the `checksum algorithms`_ section.
> +
> +It is invalid to specify a hash name without a value.
> +
> +
>  File verification
>  -----------------
>  
> -- 
> 2.37.3
> 
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [gentoo-dev] [PATCH 0/3] glep-0074: clarifications about size and checksum fields

[Michał Górny]

On Fri, 2022-09-23 at 17:58 +0000, Sheng Yu wrote:
> Hi,
> 
> The hash does not need to be lowercase. It can be a quick fix in portage to accept any case.
> 

I'm all for fixing Portage but I don't think we should be breaking
backwards compatibility over this.

-- 
Best regards,
Michał Górny

Re: [gentoo-dev] [PATCH 2/3] glep-0074: Specify the format of size and checksum fields

[Michał Górny]

On Sat, 2022-09-24 at 18:09 -0500, John Helmert III wrote:
> On Fri, Sep 23, 2022 at 04:03:54PM +0200, Michał Górny wrote:
> > Signed-off-by: Michał Górny <mgorny@gentoo.org>
> > ---
> >  glep-0074.rst | 13 +++++++++++++
> >  1 file changed, 13 insertions(+)
> > 
> > diff --git a/glep-0074.rst b/glep-0074.rst
> > index 54bf216..bfbe092 100644
> > --- a/glep-0074.rst
> > +++ b/glep-0074.rst
> > @@ -191,6 +191,19 @@ The encoding can be used for other characters as well. In particular,
> >  escaping non-printable characters might be desirable.
> >  
> >  
> > +Size and checksum fields
> > +------------------------
> > +
> > +The Manifest entries used to describe files list the file size and one
> > +or more checksums. The size is expressed as an unsigned decimal integer.
> 
> "an unsigned decimal integer" representing the file's size in bytes
> (rather than bits, or nibbles, or $UNIT), right?
> 

Very well.  I'm afraid this is going to break some existing
implementations that preferred to measure in inches but gotta live with
it.

-- 
Best regards,
Michał Górny

[gentoo-dev] [PATCH v2 0/3] glep-0074: clarifications about size and checksum fields

[Michał Górny]

Hi,

Changes in v2: clarified that size is in bytes.


Michał Górny (3):
  glep-0074: Clarify that DIST entries are specific to PMs
  glep-0074: Specify the format of size and checksum fields
  glep-0074: Clarify the hex encoding of hash values

 glep-0074.rst | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

-- 
2.37.3

[gentoo-dev] [PATCH v2 1/3] glep-0074: Clarify that DIST entries are specific to PMs

[Michał Górny]

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

diff --git a/glep-0074.rst b/glep-0074.rst
index 7f53302..54bf216 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -8,7 +8,7 @@ Type: Standards Track
 Status: Final
 Version: 1.3
 Created: 2017-10-21
-Last-Modified: 2022-09-21
+Last-Modified: 2022-09-23
 Post-History: 2017-10-26, 2017-11-16, 2018-02-08, 2022-09-08, 2022-09-11
 Content-Type: text/x-rst
 Requires: 59, 61
@@ -286,6 +286,9 @@ The Manifest files can specify the following tags:
   ``DIST`` entries apply to all packages below the Manifest file
   specifying them.
 
+  This entry is specific to package manager use and it is not used
+  when verifying local directories.
+
 
 Deprecated Manifest tags
 ------------------------
-- 
2.37.3

[gentoo-dev] [PATCH v2 2/3] glep-0074: Specify the format of size and checksum fields

[Michał Górny]

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

diff --git a/glep-0074.rst b/glep-0074.rst
index 54bf216..16cbb67 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -191,6 +191,19 @@ The encoding can be used for other characters as well. In particular,
 escaping non-printable characters might be desirable.
 
 
+Size and checksum fields
+------------------------
+
+The Manifest entries used to describe files list the file size in bytes
+and one or more checksums. The size is expressed as an unsigned decimal
+integer. The checksums are expressed using pairs of fields, with
+the first field in every pair specifying the hash name and the second
+field its value. The names of hashes and the encoding of their values
+are specified in the `checksum algorithms`_ section.
+
+It is invalid to specify a hash name without a value.
+
+
 File verification
 -----------------
 
-- 
2.37.3

[gentoo-dev] [PATCH v2 3/3] glep-0074: Clarify the hex encoding of hash values

[Michał Górny]

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

diff --git a/glep-0074.rst b/glep-0074.rst
index 16cbb67..06e961f 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -418,6 +418,14 @@ Checksum algorithms
    | ``WHIRLPOOL``   | Whirlpool [#BARRETO]_ | 512  | Hex  |             |
    +-----------------+-----------------------+------+------+-------------+
 
+The following hash value encodings are used:
+
+Hex
+  The hash value expressed as an unsigned hexadecimal integer,
+  using digits ``0`` to ``9`` and lowercase letters ``a`` to ``f``,
+  with no prefix or suffix.
+
+
 Any new hashes must be added to this specification prior to being used
 in Manifest files. Adding a new hash is considered
 a backwards-compatible change to the GLEP. It is recommended that new
-- 
2.37.3