Subject: [xml2rfc] Any recommended way to reference code on github?

From: Robert Moskowitz <[email-masked]>
Date: Tue, 14 Sep 2021 08:38:18 -0400

I have a script on github,

https://github.com/ietf-wg-drip/draft-ietf-drip-rid/blob/master/hhit-gen.py

That I want to reference in a draft.  I don't want to include the 
script, too big and it will grow still.

Is there any common practice for such an informative reference?

thanks

---

From: Julian Reschke <[email-masked]>
Date: Tue, 14 Sep 2021 14:41:31 +0200

> Is there any common practice for such an informative reference?

This might help:

https://datatracker.ietf.org/doc/html/draft-flanagan-7322bis-07#section-4.8.6.9

Best regards, Julian

---

From: Eliot Lear <[email-masked]>
Date: Tue, 14 Sep 2021 14:45:14 +0200

Reference code should be informational, and eref can do the job. The 
only question is whether to include a hash a'la:

</eref/ 
target="https://github.com/project/repo/tree/15350a39f3ae82abba663292450aba611e4e8ff3">

The benefit of this is that it won't change in ways that might be 
incompatible with a static specification such as an RFC.

Eliot

On 14.09.21 14:38, Robert Moskowitz wrote:
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc
>

---

From: Eliot Lear <[email-masked]>
Date: Tue, 14 Sep 2021 14:46:28 +0200

Just following up on this in another way, should we want to support PURLs?

---

From: Robert Moskowitz <[email-masked]>
Date: Tue, 14 Sep 2021 10:08:09 -0400

> https://datatracker.ietf.org/doc/html/draft-flanagan-7322bis-07#section-4.8.6.9 

Thanks Julian.

The example includes a short commit hash.  I see what looks like such a 
hash for my script, c4b7d1b, but it is a link that is a real long 
string.  Do I just include this short string as in the example?

---

From: Robert Moskowitz <[email-masked]>
Date: Tue, 14 Sep 2021 10:08:21 -0400

Eliot,

> incompatible with a static specification such as an RFC.

You mean like:

https://github.com/ietf-wg-drip/draft-ietf-drip-rid/commit/c4b7d1b5d99e409f4843189b8bd26797aafe75c2

?

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 14 Sep 2021 16:22:13 +0200

On 14. Sep 2021, at 16:08, Robert Moskowitz <[email-masked]> wrote:
> 
>> Reference code should be informational, and eref can do the job.  The only question is whether to include a hash a'la:
>> 
>> <eref target="https://github.com/project/repo/tree/15350a39f3ae82abba663292450aba611e4e8ff3" <https://github.com/project/repo/tree/15350a39f3ae82abba663292450aba611e4e8ff3>>
>> 
>> The benefit of this is that it won't change in ways that might be incompatible with a static specification such as an RFC.
>> 
> 
> You mean like:
> 
> https://github.com/ietf-wg-drip/draft-ietf-drip-rid/commit/c4b7d1b5d99e409f4843189b8bd26797aafe75c2 <https://github.com/ietf-wg-drip/draft-ietf-drip-rid/commit/c4b7d1b5d99e409f4843189b8bd26797aafe75c2>

I thought that the point was that the code can still change.
Giving a commit ID, but pointing to the mutable document, gets the best of both worlds.

Grüße, Carsten

---

From: Robert Moskowitz <[email-masked]>
Date: Tue, 14 Sep 2021 10:30:08 -0400

On 9/14/21 10:22 AM, Carsten Bormann wrote:
> On 14. Sep 2021, at 16:08, Robert Moskowitz <[email-masked] 
> <mailto:[email-masked]>> wrote:
>>
>>> Reference code should be informational, and eref can do the job.  
>>> The only question is whether to include a hash a'la:
>>>
>>> </eref/target="https://github.com/project/repo/tree/15350a39f3ae82abba663292450aba611e4e8ff3">
>>>

I see your point and for this script I definitely agree.  We plan on 
improving this script.

---

From: Robert Moskowitz <[email-masked]>
Date: Tue, 14 Sep 2021 10:36:38 -0400

> Giving a commit ID, but pointing to the mutable document, gets the 

As I am constructing the ref xml, I am thinking what date I put in. the 
date of the commit or the date we wrote the script?  And how do I get 
that commit hash into the reference?

thanks

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 14 Sep 2021 18:12:13 +0200

On 2021-09-14, at 16:36, Robert Moskowitz <[email-masked]> wrote:
> 
> As I am constructing the ref xml, I am thinking what date I put in.  

Date of last commit, I’d say.

> the date of the commit or the date we wrote the script?  And how do I get that commit hash into the reference?

Like this:

  hhit-py:
    target: https://github.com/ietf-wg-drip/draft-ietf-drip-rid/blob/master/hhit-gen.py
    title: draft-ietf-drip-rid/hhit-gen.py at master · ietf-wg-drip/draft-ietf-drip-rid
    date: 2021-09-10
    rc: commit c4b7d1b

(Or, in XML:

<reference anchor="hhit-py" target="https://github.com/ietf-wg-drip/draft-ietf-drip-rid/blob/master/hhit-gen.py">
  <front>
    <title>draft-ietf-drip-rid/hhit-gen.py at master · ietf-wg-drip/draft-ietf-drip-rid</title>
    <author >
      <organization></organization>
    </author>
    <date year="2021" month="September" day="10"/>
  </front>
<refcontent>commit c4b7d1b</refcontent></reference>

This is what you get:

   [hhit-py]  "draft-ietf-drip-rid/hhit-gen.py at master · ietf-wg-drip/
              draft-ietf-drip-rid", commit c4b7d1b, 10 September 2021,
              <https://github.com/ietf-wg-drip/draft-ietf-drip-
              rid/blob/master/hhit-gen.py>.

Grüße, Carsten

---

From: Marc Petit-Huguenin <[email-masked]>
Date: Tue, 14 Sep 2021 09:29:06 -0700

>                rid/blob/master/hhit-gen.py>.

You do not need to indicate the branch -- the commit-id is unique in a repository.

-- 
Marc Petit-Huguenin
Email: [email-masked]
Blog: https://marc.petit-huguenin.org
Profile: https://www.linkedin.com/in/petithug

---

From: Julian Reschke <[email-masked]>
Date: Tue, 14 Sep 2021 20:23:52 +0200

Am 14.09.2021 um 18:12 schrieb Carsten Bormann:
> ...

Or, simpler:

reference anchor="hhit-py"
target="https://github.com/ietf-wg-drip/draft-ietf-drip-rid/blob/master/hhit-gen.py">
   <front>
     <title>draft-ietf-drip-rid/hhit-gen.py at master ·
ietf-wg-drip/draft-ietf-drip-rid</title>
     <author/>
     <date year="2021" month="September" day="10"/>
   </front>
<refcontent>commit c4b7d1b</refcontent></reference>

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 14 Sep 2021 20:29:15 +0200

> You do not need to indicate the branch -- the commit-id is unique in a repository.

Again, the point was that this is a reference to a document that is being updated (and, to make the librarians happy, to a specific version of it as well).

Grüße, Carsten

---

From: Marc Petit-Huguenin <[email-masked]>
Date: Tue, 14 Sep 2021 11:59:49 -0700

> Again, the point was that this is a reference to a document that is being updated (and, to make the librarians happy, to a specific version of it as well).

Sure, in that case use only the branch but not the commit-id.  This is similar to an Internet-Draft reference -- either use the name with the version number at the end, which means use that precise version of the Internet-Draft (this is equivalent of using the commit-id); or use the I-D without the version prefix, which means use that whatever is the latest version of that internet-draft, including the final RFC (this is equivalent of using the branch).

---

From: Robert Moskowitz <[email-masked]>
Date: Tue, 14 Sep 2021 15:57:11 -0400

On 9/14/21 2:59 PM, Marc Petit-Huguenin wrote:
>> Again, the point was that this is a reference to a document that is 
>> being updated (and, to make the librarians happy, to a specific 
>> version of it as well).
>>
>
> Sure, in that case use only the branch but not the commit-id. This is 
> similar to an Internet-Draft reference -- either use the name with the 
> version number at the end, which means use that precise version of the 
> Internet-Draft (this is equivalent of using the commit-id); or use the 
> I-D without the version prefix, which means use that whatever is the 
> latest version of that internet-draft, including the final RFC (this 
> is equivalent of using the branch).
>

Ah, got it.  So as we expect this script to improve (the programmer as 
already putting final touches on next ver), then leave of the commit 
ID.  Though for something like this it would be "nice" to get the date 
from Github, as the date would need to be updated with each new ver of 
the script.

---

From: Sandy Ginoza <[email-masked]>
Date: Tue, 14 Sep 2021 16:19:11 -0700

Hi all,

Just an fyi that Carsten’s suggestion aligns with the RFC Style Guide as well: 
https://www.rfc-editor.org/styleguide/part2/#ref_repo

We use the date of the last commit to note what was available when the document was published.  The link enables readers to find the most current documentation.  

Thanks,
Sandy 

> On Sep 14, 2021, at 9:12 AM, Carsten Bormann <[email-masked]> wrote:
>