Important: Candidate for new Approved Specification, v1.1. Review Period starts

Roberto Di Cosmo

unread,

Oct 18, 2023, 1:36:33 PM10/18/23

to swhid-...@googlegroups.com

Dear all,

we have been improving the first Approved Specification, v1.0 for quite a while since its official announcement on June 21st, and with the last issues spotted by Alexios (thanks!) properly addressed, we are now in good shape to move forward towards the v1.1 that will be the version that we'd like to send to the ISO fast track process.

As a consequence, the current status of the specification, version 1.1, is now officially a Candidate for Approved Specification.

According to the governance document, we now call all of you to review the current document that will last for a two-week period, and if no major issues arise, we will then be able to announce v1.1 as the new “Approved Specification”.

Here is the planned timeline:

October 30th 2023 (today): start of the review period, triggered by this email
November 2nd 2023 : end of the review period, last call for comments
Monday November 6th : if no blockers, formal announcement of the Approved Specification 1.1

Looking forward to your help!

--

Roberto (on behalf or the SWHID specification core team)

Robbie Morrison

unread,

Oct 19, 2023, 6:08:53 AM10/19/23

to swhid-...@googlegroups.com

Hello list

I just read v1.1 carefully, also looking for any language issues. The overall message is completely clear — most of the following is really just splitting hairs. And only a couple of changes are marked "mandatory".

with best wishes, Robbie

Copyright

the Community Specification License 1.0 SPDX of "Community-Spec-1.0" could be added?
a URL to the license text could be added?

Forward

the "XXX" stand‑in for contributors needs completing

1 Scope

referencing digital artifacts that fit in the data model: "that fit in" → "that match" or even "that fit with" would be better (language improvement)
"by anyone that has access to a copy of them" → "copy of those objects" (to remove any possible ambiguity)
I would personally write out "i.e." as "that is" (three extra chars and easier to read)

3 Terms and definitions

" (in a structure often visualized as a tree)" → DELETE (because that notion is adequately covered in the next sentence)
"without needing a registry" → "without needing access to a registry" (splitting hairs?)
"but not limited to source code, build scripts, documentation, etc" → DELETE "etc" and add "and" where needed (etc adds nothing)
"such as version number, author, date of the last modification, etc" → DELETE "etc" and add "and" where needed (etc adds nothing)
"might not exist for it" → "for that object" (again to remove any possible ambiguity)
"and branching and merging of code" → "and the branching and" (the added "the" helps but is not mandatory)
should software "object" or software "artifact" or both be defined?
should "percent encoded" be defined?
should "metadata" be defined? Or at least accorded a short paragraph somewhere to introduce the idea? Particularly as this concept is part of the SWHID specification.
should "Unix epoch" be defined?
should "OpenPGP" be defined. Or at least accorded a sentence somewhere?
should "tarball" be defined. Or at least accorded a short explanation somewhere? Or written less colloquially in the text as "tarred archive file" or "compressed archive file" instead?

4 Syntax

does the concept of "ASCII" need reference to a specification? (perhaps?)
does "NULL byte" need an explanation? (possibly not?)
"(in particular, notice that there is no file name mentioned here)" → "(in particular, the SWHID does not embed the name of the file when referencing content)" (is that the meaning sought, I am puzzled otherwise, I realize this remark is under to "Contents" header but others might not notice)

5 Core identifiers

"juxtaposing" → "juxtaposing:" (missing colon and mandatory)
"May 4th 2017" → "4 May 2017" (optional, a matter of style)
"in that directory and record their changes" → "in that directory and records their changes" (now plural and mandatory)
"Each release points to the last commit in project history corresponding to the release" → "corresponding to that release" (for clarity)
"The supported metadata is as follows:" → "The metadata fields supported by SWHID are as follows:" (better with active voice)
"e.g." → "for instance"
"suite of a FOSS distribution" → "suite of an open source distribution" (mandatory I think. FOSS is a rather rarefied abbreviation)

6 Qualified identifiers

"Byte numbers start from 0, and range is inclusive" → "Byte numbers start from 0, and the range is inclusive" (mandatory)
"This qualifier may be helpful to get hold of the full repository" → "This qualifier may help to get" (more direct)

General observations by me

some particular chars are highlighted red, others set in single quotes and remain black → perhaps the typesetting of char could be more consistent
the LF may need explaining: which convention? Unix and Unix‑like? Anything goes? References to the "ASCII LF character" need clarifying, could also be "\r" or is that okay, tolerated, rejected?

Closure

I have been looking recently at the language and definitions in the proposed EU Cyber Resilience Act (CRA). I could see no issues with respect to the SWHID specification in that context. But I wonder, going forward, if the SWHIDs, once standardized, could be usefully referenced in future CRA good practice advice?

Many thanks to Roberto and team for this important initiative.

--
You received this message because you are subscribed to the Google Groups "SWHID (Software Heritage Identifiers) discussions" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swhid-discus...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/swhid-discuss/CAJBwKuVxbbUeUK2kF%2BZH%2B39y7rCSH7PmPJdbr-yGCqz0hHEEsA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

-- 
Robbie Morrison
Address: Schillerstrasse 85, 10627 Berlin, Germany
Phone: +49.30.612-87617

Robbie Morrison

unread,

Oct 19, 2023, 6:16:45 AM10/19/23

to swhid-...@googlegroups.com

Oh and regarding:

"The computation of the SWHID identifiers is based on Merkle Acyclic Directed Graphs"
"a node in the Merkle DAG"

So would this be better at the first instance (for consistency):

"Merkle Directed Acyclic Graphs (DAG)"

Robbie

To view this discussion on the web visit https://groups.google.com/d/msgid/swhid-discuss/32a9f1d3-53ea-4a46-ba76-11fdb779901d%40posteo.de.

For more options, visit https://groups.google.com/d/optout.

Zavras, Alexios

unread,

Oct 19, 2023, 7:08:04 AM10/19/23

to Robbie Morrison, swhid-...@googlegroups.com

Many thanks for all this, Robbie!

--

zvr

To view this discussion on the web visit https://groups.google.com/d/msgid/swhid-discuss/2f2d0669-bf5c-4dfe-94d2-b29dc171b54d%40posteo.de.

For more options, visit https://groups.google.com/d/optout.

Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de
Managing Directors: Christin Eisenschmid, Sharon Heck, Tiffany Doon Silva
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928

Roberto Di Cosmo

unread,

Oct 19, 2023, 5:33:09 PM10/19/23

to Robbie Morrison, swhid-...@googlegroups.com

Hi Robbie,

I join my voice to Alexios to say thank you for the careful rereading.

May I ask you to go an extra mile, and prepare a PR with all the changes that are text improvements? I would be quite helpful :-)

--

Roberto

To view this discussion on the web visit https://groups.google.com/d/msgid/swhid-discuss/32a9f1d3-53ea-4a46-ba76-11fdb779901d%40posteo.de.

Robbie Morrison

unread,

Oct 19, 2023, 5:41:05 PM10/19/23

to swhid-...@googlegroups.com

Hello Roberto

Sure. Just checking, should I clone this: https://github.com/swhid/specification/tree/main

Robbie

To view this discussion on the web visit https://groups.google.com/d/msgid/swhid-discuss/CAJBwKuWFnr7Teh9mpPuJmnOBx7XCCTAu3nZT0k9fqGo4JHyqkA%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

Roberto Di Cosmo

unread,

Oct 20, 2023, 3:49:08 AM10/20/23

to Robbie Morrison, swhid-...@googlegroups.com

Yes, indeed ;-)

On Thu, Oct 19, 2023 at 09:41:02PM +0000, Robbie Morrison wrote:
> Hello Roberto
>
> Sure. Just checking, should I clone this:

> [1]https://github.com/swhid/specification/tree/main

>
> Robbie
>
> On 19/10/2023 23.32, Roberto Di Cosmo wrote:
>
> Hi Robbie,
> I join my voice to Alexios to say thank you for the careful
> rereading.
> May I ask you to go an extra mile, and prepare a PR with all the
> changes that are text improvements? I would be quite helpful :-)
> --
> Roberto
>
> On Thu, 19 Oct 2023 at 12:08, Robbie Morrison
> <[2]robbie....@posteo.de> wrote:
>
> Hello list
>
> I just read v1.1 carefully, also looking for any language issues. The
> overall message is completely clear — most of the following is really
> just splitting hairs. And only a couple of changes are marked
> "mandatory".
>
> with best wishes, Robbie
>
> Copyright
>

> * the Community Specification License 1.0 SPDX of
> "Community-Spec-1.0" could be added?
> * a URL to the license text could be added?
>
> Forward
>
> 1. the "XXX" stand‑in for contributors needs completing
>
> 1 Scope
>
> 1. referencing digital artifacts that fit in the data model: "that fit

> in" → "that match" or even "that fit with" would be better
> (language improvement)

> 2. "by anyone that has access to a copy of them" → "copy of those

> objects" (to remove any possible ambiguity)

> 3. I would personally write out "i.e." as "that is" (three extra chars

> and easier to read)
>
> 3 Terms and definitions
>

> 1. " (in a structure often visualized as a tree)" → DELETE (because

> that notion is adequately covered in the next sentence)

> 2. "without needing a registry" → "without needing access to a
> registry" (splitting hairs?)
> 3. "but not limited to source code, build scripts, documentation, etc"

> → DELETE "etc" and add "and" where needed (etc adds nothing)

> 4. "such as version number, author, date of the last modification,

> etc" → DELETE "etc" and add "and" where needed (etc adds nothing)

> 5. "might not exist for it" → "for that object" (again to remove any
> possible ambiguity)
> 6. "and branching and merging of code" → "and the branching and" (the

> added "the" helps but is not mandatory)

> 7. should software "object" or software "artifact" or both be defined?
> 8. should "percent encoded" be defined?
> 9. should "metadata" be defined? Or at least accorded a short

> paragraph somewhere to introduce the idea? Particularly as this
> concept is part of the SWHID specification.

> 10. should "Unix epoch" be defined?
> 11. should "OpenPGP" be defined. Or at least accorded a sentence
> somewhere?
> 12. should "tarball" be defined. Or at least accorded a short

> explanation somewhere? Or written less colloquially in the text as
> "tarred archive file" or "compressed archive file" instead?
>
> 4 Syntax
>

> 1. does the concept of "ASCII" need reference to a specification?
> (perhaps?)
> 2. does "NULL byte" need an explanation? (possibly not?)
> 3. "(in particular, notice that there is no file name mentioned here)"

> → "(in particular, the SWHID does not embed the name of the file
> when referencing content)" (is that the meaning sought, I am
> puzzled otherwise, I realize this remark is under to "Contents"
> header but others might not notice)
>
> 5 Core identifiers
>

> 1. "juxtaposing" → "juxtaposing:" (missing colon and mandatory)
> 2. "May 4th 2017" → "4 May 2017" (optional, a matter of style)
> 3. "in that directory and record their changes" → "in that directory

> and records their changes" (now plural and mandatory)

> 4. "Each release points to the last commit in project history

> corresponding to the release" → "corresponding to that release"
> (for clarity)

> 5. "The supported metadata is as follows:" → "The metadata fields

> supported by SWHID are as follows:" (better with active voice)

> 6. "e.g." → "for instance"
> 7. "suite of a FOSS distribution" → "suite of an open source

> distribution" (mandatory I think. FOSS is a rather rarefied
> abbreviation)
>
> 6 Qualified identifiers
>

> 1. "Byte numbers start from 0, and range is inclusive" → "Byte numbers

> start from 0, and the range is inclusive" (mandatory)

> 2. "This qualifier may be helpful to get hold of the full repository"

> → "This qualifier may help to get" (more direct)
>
> General observations by me
>

> 1. some particular chars are highlighted red, others set in single

> quotes and remain black → perhaps the typesetting of char could be
> more consistent

> 2. the LF may need explaining: which convention? Unix and Unix‑like?

> Anything goes? References to the "ASCII LF character" need
> clarifying, could also be "\r" or is that okay, tolerated,
> rejected?
>
> Closure
>
> I have been looking recently at the language and definitions in the
> proposed EU Cyber Resilience Act (CRA). I could see no issues with
> respect to the SWHID specification in that context. But I wonder, going
> forward, if the SWHIDs, once standardized, could be usefully referenced
> in future CRA good practice advice?
>
> Many thanks to Roberto and team for this important initiative.

> _______________________________________________________________________

>
> On 18/10/2023 19.36, Roberto Di Cosmo wrote:
>
> Dear all,

> we have been improving [3]the first Approved Specification, v1.0 for

> quite a while since its official announcement on June 21st, and with
> the last issues spotted by Alexios (thanks!) properly addressed, we are
> now in good shape to move forward towards the v1.1 that will be the
> version that we'd like to send to the ISO fast track process.

> As a consequence, [4]the current status of the specification, version

> 1.1, is now officially a Candidate for Approved Specification.
> According to the governance document, we now call all of you to review
> the current document that will last for a two-week period, and if no
> major issues arise, we will then be able to announce v1.1 as the new
> “Approved Specification”.
> Here is the planned timeline:

> * October 30th 2023 (today): start of the review period, triggered by
> this email
> * November 2nd 2023 : end of the review period, last call for
> comments
> * Monday November 6th : if no blockers, formal announcement of the

> Approved Specification 1.1
>
> Looking forward to your help!
> --

> Roberto (on behalf or the [5]SWHID specification core team)

>
> --
> You received this message because you are subscribed to the Google
> Groups "SWHID (Software Heritage Identifiers) discussions" group.
> To unsubscribe from this group and stop receiving emails from it,

> send an email to [6]swhid-discus...@googlegroups.com.

> To view this discussion on the web visit

> [7]https://groups.google.com/d/msgid/swhid-discuss/CAJBwKuVxbbUeUK2k
> F%2BZH%2B39y7rCSH7PmPJdbr-yGCqz0hHEEsA%40mail.gmail.com.
> For more options, visit [8]https://groups.google.com/d/optout.

>
> --
> Robbie Morrison
> Address: Schillerstrasse 85, 10627 Berlin, Germany
> Phone: +49.30.612-87617
>
> --
> You received this message because you are subscribed to the Google
> Groups "SWHID (Software Heritage Identifiers) discussions" group.
> To unsubscribe from this group and stop receiving emails from it,

> send an email to [9]swhid-discus...@googlegroups.com.

> To view this discussion on the web visit

> [10]https://groups.google.com/d/msgid/swhid-discuss/32a9f1d3-53ea-4a
> 46-ba76-11fdb779901d%40posteo.de.
> For more options, visit [11]https://groups.google.com/d/optout.

>
> --
> You received this message because you are subscribed to the Google
> Groups "SWHID (Software Heritage Identifiers) discussions" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to [12]swhid-discus...@googlegroups.com.

> To view this discussion on the web visit

> [13]https://groups.google.com/d/msgid/swhid-discuss/CAJBwKuWFnr7Teh9mpP
> uJmnOBx7XCCTAu3nZT0k9fqGo4JHyqkA%40mail.gmail.com.
> For more options, visit [14]https://groups.google.com/d/optout.

> --
> Robbie Morrison
> Address: Schillerstrasse 85, 10627 Berlin, Germany
> Phone: +49.30.612-87617
>
> --
> You received this message because you are subscribed to the Google
> Groups "SWHID (Software Heritage Identifiers) discussions" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to [15]swhid-discus...@googlegroups.com.

> To view this discussion on the web visit

> [16]https://groups.google.com/d/msgid/swhid-discuss/dd68c498-970c-437c-
> a380-110f7d116292%40posteo.de.
> For more options, visit [17]https://groups.google.com/d/optout.
>
> References
>
> 1. https://github.com/swhid/specification/tree/main
> 2. mailto:robbie....@posteo.de
> 3. http://www.swhid.org/specification
> 4. http://www.swhid.org/specification/dev/
> 5. https://swhid.org/
> 6. mailto:swhid-discus...@googlegroups.com
> 7. https://groups.google.com/d/msgid/swhid-discuss/CAJBwKuVxbbUeUK2kF+ZH+39y...@mail.gmail.com?utm_medium=email&utm_source=footer
> 8. https://groups.google.com/d/optout
> 9. mailto:swhid-discus...@googlegroups.com
> 10. https://groups.google.com/d/msgid/swhid-discuss/32a9f1d3-53ea-4a46...@posteo.de?utm_medium=email&utm_source=footer
> 11. https://groups.google.com/d/optout
> 12. mailto:swhid-discus...@googlegroups.com
> 13. https://groups.google.com/d/msgid/swhid-discuss/CAJBwKuWFnr7Teh9mpPuJmnOB...@mail.gmail.com?utm_medium=email&utm_source=footer
> 14. https://groups.google.com/d/optout
> 15. mailto:swhid-discus...@googlegroups.com
> 16. https://groups.google.com/d/msgid/swhid-discuss/dd68c498-970c-437c...@posteo.de?utm_medium=email&utm_source=footer
> 17. https://groups.google.com/d/optout

--

--
Roberto Di Cosmo

------------------------------------------------------------------
Computer Science Professor
(on leave at INRIA from IRIF/Université Paris Cité)

Director
Software Heritage https://www.softwareheritage.org
INRIA http://y2u.be/Ez4xKTKJO2o
Bureau C328 E-mail : rob...@dicosmo.org
2, Rue Simone Iff Web page : http://www.dicosmo.org
CS 42112 Twitter : http://twitter.com/rdicosmo
75589 Paris Cedex 12 Tel : +33 1 80 49 44 42
------------------------------------------------------------------
GPG fingerprint 2931 20CE 3A5A 5390 98EC 8BFC FCCA C3BE 39CB 12D3

Robbie Morrison

unread,

Oct 21, 2023, 5:44:36 PM10/21/23

to swhid-...@googlegroups.com

Hi Roberto

I guess it would be useful to group the PRs into sensible sets of changes? Or would one monolithic PR be fine?

Robbie

Roberto Di Cosmo

unread,

Oct 22, 2023, 4:28:31 AM10/22/23

to Robbie Morrison, swhid-...@googlegroups.com

Hi Robbie,
indeed, the best way is to create separate PRs for the language
improvements on one side, that can be a single monolithic PR, and
the points that you thing require more discussion.

--
Roberto

On Sat, Oct 21, 2023 at 09:44:32PM +0000, Robbie Morrison wrote:
> Hi Roberto
>
> I guess it would be useful to group the PRs into sensible sets of
> changes? Or would one monolithic PR be fine?
>
> Robbie
>
> On 20/10/2023 09.49, Roberto Di Cosmo wrote:
>
> Yes, indeed ;-)
>
> On Thu, Oct 19, 2023 at 09:41:02PM +0000, Robbie Morrison wrote:
>
> Hello Roberto
>
> Sure. Just checking, should I clone this:

> [1][1]https://github.com/swhid/specification/tree/main

> send an email to [[3]6]swhid-discus...@googlegroups.com.

> To view this discussion on the web visit

> [7][4]https://groups.google.com/d/msgid/swhid-discuss/CAJBwKuVxbbUeUK2k
> F%2BZH%2B39y7rCSH7PmPJdbr-yGCqz0hHEEsA%40mail.gmail.com.
> For more options, visit [8][5]https://groups.google.com/d/optout.

>
> --
> Robbie Morrison
> Address: Schillerstrasse 85, 10627 Berlin, Germany
> Phone: +49.30.612-87617
>
> --
> You received this message because you are subscribed to the Google
> Groups "SWHID (Software Heritage Identifiers) discussions" group.
> To unsubscribe from this group and stop receiving emails from it,

> send an email to [[6]9]swhid-discus...@googlegroups.com.

> To view this discussion on the web visit

> [10][7]https://groups.google.com/d/msgid/swhid-discuss/32a9f1d3-53ea-4a
> 46-ba76-11fdb779901d%40posteo.de.
> For more options, visit [11][8]https://groups.google.com/d/optout.

>
> --
> You received this message because you are subscribed to the Google
> Groups "SWHID (Software Heritage Identifiers) discussions" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to [[9]12]swhid-discus...@googlegroups.com.

> To view this discussion on the web visit

> [13][10]https://groups.google.com/d/msgid/swhid-discuss/CAJBwKuWFnr7Teh9mpP
> uJmnOBx7XCCTAu3nZT0k9fqGo4JHyqkA%40mail.gmail.com.
> For more options, visit [14][11]https://groups.google.com/d/optout.

> --
> Robbie Morrison
> Address: Schillerstrasse 85, 10627 Berlin, Germany
> Phone: +49.30.612-87617
>
> --
> You received this message because you are subscribed to the Google
> Groups "SWHID (Software Heritage Identifiers) discussions" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to [[12]15]swhid-discus...@googlegroups.com.

> To view this discussion on the web visit

>
>
> --
> Robbie Morrison
> Address: Schillerstrasse 85, 10627 Berlin, Germany
> Phone: +49.30.612-87617
>

> --
> You received this message because you are subscribed to the Google
> Groups "SWHID (Software Heritage Identifiers) discussions" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to [32]swhid-discus...@googlegroups.com.

> To view this discussion on the web visit

Roberto Di Cosmo

unread,

Nov 2, 2023, 3:01:14 AM11/2/23

to swhid-...@googlegroups.com

Dear all,

this is the last call for comments on the current status of the specification that incorporates the changes to fix the issues that have been identified during this review period (and many thanks to those of you who carefully re-read it and improved this new version!).

This is now the official Candidate for Approved Specification: if no blockers are identified, it will become our Approved Specification, version 1.1, this Monday November 6th.

--

Roberto (on behalf of the SWHID specification core team)

Robbie Morrison

unread,

Nov 2, 2023, 6:50:17 AM11/2/23

to swhid-...@googlegroups.com

please note: https://github.com/swhid/specification/pull/53

On 02/11/2023 08.00, Roberto Di Cosmo wrote:

Dear all,

this is the last call for comments on the current status of the specification that incorporates the changes to fix the issues that have been identified during this review period (and many thanks to those of you who carefully re-read it and improved this new version!).

This is now the official Candidate for Approved Specification: if no blockers are identified, it will become our Approved Specification, version 1.1, this Monday November 6th.

--

Roberto (on behalf of the SWHID specification core team)

<snip>

Reply all

Reply to author

Forward