Subject: [rfc-i] GitHub references

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Thu, 8 Mar 2018 11:59:26 -0800

Hello all,

The RFC Editor is proposing to update the reference format for
informative references to GitHub repositories (noting that GitHub
repositories are not currently accepted as normative references).
Specifically, we propose to standardize on the following:

1) No author name(s). A repository may have many contributors, and there
is no way to easily determine major contributors versus all others.

2) The title of the repository will be whatever is in the top left of
the main repository page.

3) The URL will be to the main page of the repository.

4) The reference will not include any particular commit hash. It will
include the date of the last commit at the time the RFC-to-be is edited.

So:

OLD
   [mpingSource]
              Fan, X., Mathis, M., and D. Hamon, "Git Repository for
              mping: An IP Level Performance Diagnostic", Sept 2013,
              <https://github.com/m-lab/mping>.

NEW
   [mpingSource]
              "mping", July 2016, <https://github.com/m-lab/mping>.

Does anyone have any feedback re: the above proposal? This is outside
the realm of CMOS today, so we're breaking some new ground here.

Thanks!
Heather Flanagan, RSE

_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Bob Hinden <[email-masked]>
Date: Thu, 8 Mar 2018 13:46:58 -0800

Heather,

> On Mar 8, 2018, at 11:59 AM, Heather Flanagan (RFC Series Editor) <[email-masked]> wrote:
> 
> 
> Hello all,
> 

Why not also include the full title, for example:

   [mpingSource]
              "mping: An IP Level Performance Diagnostic", July 2016, <https://github.com/m-lab/mping>.

I think that would make the reference more descriptive.

Thanks,
Bob

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Thu, 8 Mar 2018 13:54:27 -0800

> I think that would make the reference more descriptive.

Hi Bob,

Where do you see the full title? Is it in a location consistent from one
repository to the next?

thanks,
Heather

---

From: "Paul Hoffman" <[email-masked]>
Date: Thu, 08 Mar 2018 17:58:23 -0400

> Where do you see the full title? Is it in a location consistent from 

This is a problem with GitHub: the "title" of a repo can change easily 
over time. Having said that, it might be OK to use the title at the time 
of publication. Humorously, for mping, right now that is empty.

--Paul Hoffman

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 9 Mar 2018 11:26:10 +1300

> of publication. Humorously, for mping, right now that is empty.

And that is not something the RFC Editor can fix. However, I think that
the rule should be: use the repo's title if there is one. For example,
https://github.com/becarpenter/graspy has a title that would suffice, IMNSHO.

    Brian

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Thu, 8 Mar 2018 14:31:51 -0800

> https://github.com/becarpenter/graspy has a title that would suffice, IMNSHO.

I'm still unclear on what and where the title is that you're referring
to. Are we talking about what ever is in the area that on mping says
"/No description, website, or topics provided." /and on graspy says
"Python 3 demo code for GRASP protocol"? If that's it, that's a bit
concerning since the text might not be very title-ish at all.

-Heather//

---

From: Jim Schaad <[email-masked]>
Date: Thu, 8 Mar 2018 14:32:39 -0800

> -----Original Message-----
> From: rfc-interest [mailto:[email-masked]] On Behalf Of
> Heather Flanagan (RFC Series Editor)
> Sent: Thursday, March 8, 2018 11:59 AM
> To: [email-masked]
> Subject: [rfc-i] GitHub references
> 
> 
> Hello all,
> 
> The RFC Editor is proposing to update the reference format for informative
> references to GitHub repositories (noting that GitHub repositories are not
> currently accepted as normative references).
> 1) No author name(s). A repository may have many contributors, and there is
> no way to easily determine major contributors versus all others.
> 
> 2) The title of the repository will be whatever is in the top left of the main
> repository page.
> 
> 4) The reference will not include any particular commit hash. It will include
> the date of the last commit at the time the RFC-to-be is edited.
> 
> So:
> 
> OLD
>    [mpingSource]
> Does anyone have any feedback re: the above proposal? This is outside the
> realm of CMOS today, so we're breaking some new ground here.

I have a couple of things that I am trying to think about.  I am not sure that I think that having the github org just in the URL is sufficient.   If I look at one of my repositories, the string at the top left is "Com-AugustCellars/RfcEditor" so at a minimum you may want to expand your definition a bit more.

I think that you might want to have the ability to reference a branch that is not the main branch.  For some cases, esp. if on is referring to an implementation of a specification, it may only be on a single branch and not on the master branch at that point.  I do not have a problem w/ not having the commit hash as long as there is a date because one can do a reconstruction if necessary.

Jim

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 9 Mar 2018 11:38:52 +1300

> concerning since the text might not be very title-ish at all.

That's it, and you're right, there is no quality control on that paricular
aspect of GitHub. (That was a joke. There's no QC on any aspect of GitHub
content.)

Don't you think the authors should be expected to provide a suitable
text string? I don't think we can get this right by defining an algorithm,
and with no title at all, the references look very thin.

    Brian

---

From: Ronald Tse <[email-masked]>
Date: Thu, 8 Mar 2018 23:09:03 +0000

I fully agree with Brian that there should be a title if it exists; without a title it feels just like a footnote instead of a reference. To me something less “title-ish” is better than “title-less”.

Of course it is up to the owner of the repo to provide a proper “title", but hopefully if this practice takes up people will start giving titles…

Ron
_____________________________________

Ronald Tse
Ribose Inc.

On Mar 9, 2018, at 6:38 AM, Brian E Carpenter <[email-masked]<mailto:[email-masked]>> wrote:

Where do you see the full title? Is it in a location consistent from
one
repository to the next?

   Brian
_______________________________________________
rfc-interest mailing list
[email-masked]<mailto:[email-masked]>
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Martin Thomson <[email-masked]>
Date: Fri, 9 Mar 2018 11:16:44 +1100

Can you explain your concerns with using hashes?

"July 2016" is effectively meaningless.  Even if the month has passed
and you verify that the content was the same throughout, git has this
wonderful way of adding new content with old timestamps.

I would be far more confident if you included a hash.  A short hash is
sufficient.  For mping, "80a5713866" would describe the current state.

On the title thing Paul pointed to, I agree with others that a title
is valuable.  It is reasonable to use the repo name as the title if
one is not set.  Or, to take the first header from the README if that
appears to be better.  Use discretion if they differ.  Bob's
suggestion draws on content that isn't in the source, which concerns
me.

---

From: Martin J. Dürst <[email-masked]>
Date: Fri, 9 Mar 2018 14:25:28 +0900

I concur with all the comments up to now. It looks to me like this 
proposal was made in order to avoid any manual (or better "brainial") 
intervention, at the cost of understandability to the reader. In my 
opinion, that's backwards.

Re. authors: It's true that many repositories have many contributors. 
But many more have a single contributor. Also, in some cases, it's very 
clear who is the main contributor, at least to insiders. So not having 
authors for the cases where that doesn't make sense is okay to me. But 
disallowing authors even for the case where it would be very helpful to 
have them (maybe with an "et al." to make sure nobody is left out) 
doesn't make sense.

As for titles, one should be aware of the fact that in opposition to 
authors of I-Ds, RFCs, academic papers,..., the title isn't something a 
github committer is very much concerned about. So I could easily imagine 
allowing additions such as "Git Repository for" to titles, if the 
authors of the citing documents think that's helpful for the readers.

Also, please remember that github not only has repositories, but also 
issues, pull requests, and so on, which may occasionally need citation.

Regards,   Martin.

---

From: "Eggert, Lars" <[email-masked]>
Date: Fri, 9 Mar 2018 07:10:26 +0000

+1 on allowing hashes

Nothing else is really an archival reference 

-- 
Sent from a mobile device; please excuse typos.
+49 151 120 55791

> On Mar 9, 2018, at 01:17, Martin Thomson <[email-masked]> wrote:
>

---

From: Ronald Tse <[email-masked]>
Date: Fri, 9 Mar 2018 15:42:15 +0000

It would be great to lock into a certain state — but as it is with publishing, the content can still change. A force push or a rebase could effectively remove that commit (hash) from the git repo.

Don’t get me wrong, I’m all for allowing the addition of a commit hash, the more details provided the clearer to the reader. It’s just is not not a permanent reference, and hence not a silver bullet.

Allow me to slightly rewind the discussion — what is the intention to cite git repositories (I assume that non-GitHub repositories like GitLab are also meant to be supported)?

I’m going to quote from ISO 690, the international standard that provides bibliographic citation guidelines. Here are few relevant examples.

(In bibliography, the “viewed: [date]” / “accessed: [date]" phrases are often used to indicate the uncertainty of the current content, and is accepted practice.)

1. If the intention is to cite computer software contained in the git repo, ISO 690 gives these examples:

(no commit)
EXAMPLE 2      MOZILLA FOUNDATION. Mozilla Firefox [software]. Available from: https://www.mozilla.org/. Path: Download Firefox. [accessed 2017-06-27].

(with commit)
EXAMPLE4    Linux kernel. V3.16.3, commit b5cf3193759f7cd1cfbeef11f5cf067bbce22e55. [software]. Linus Torvalds, 2014. [created 2014-09-13T11:30:10-0700]. See also: https://en.wikipedia.org/wiki/Linux.

2. If the intention is to cite content provided by the git repo, the relevant examples are:

(no archival link)
EXAMPLE 5      INTERNATIONAL ISBN AGENCY. E-Books and ISBNs: a position paper and action points from the International ISBN Agency [online]. [London]: International ISBN Agency, 2010. Available from: http://www.isbn.org/sites/default/files/images/isbn_agency_e-books_position_paper.pdf. [viewed 2012-02-06].

(with archival link)
EXAMPLE 6      Internet forum. Wikipedia: The Free Encyclopedia. 26 May 2017, 11:05. Available from: https://en.wikipedia.org/wiki/Internet_forum. [viewed 2017-06-01]. Archived copy available from: https://web.archive.org/web/20170702110010/http://en.wikipedia.org/wiki/Internet_forum. [viewed 2017-07-04].

Hope this helps!

Kind regards,
Ron

Ronald Tse
Ribose Inc.

On Mar 9, 2018, at 3:10 PM, Eggert, Lars <[email-masked]<mailto:[email-masked]>> wrote:

+1 on allowing hashes

On Mar 9, 2018, at 01:17, Martin Thomson <[email-masked]<mailto:[email-masked]>> wrote:

On Fri, Mar 9, 2018 at 6:59 AM, Heather Flanagan (RFC Series Editor)
<[email-masked]<mailto:[email-masked]>> wrote:

Hello all,

So:

OLD
 [mpingSource]

NEW
 [mpingSource]

Thanks!
Heather Flanagan, RSE

---

From: Martin Thomson <[email-masked]>
Date: Sat, 10 Mar 2018 09:28:23 +1100

The intent is to reference the code.  Not a build artefact.
Referencing a repository is entirely appropriate.  You will note that
your examples include a commit hash.

As for your concerns about hashes, yes, in general they can be lost.
git gc can do that.  But you need to take special steps to do that and
those steps are about as socially acceptable as deleting the
repository.  Besides, forks of the repo will still have the commit, it
just takes a little more effort to find it.

Also I understand that GitHub doesn't gc, so commits aren't lost
unless the repository goes away completely.  Even if the branch or tag
no longer refers to the hash, it remains on their servers.  I know
this from painful experience of having to recover from a forced push.

On Sat, Mar 10, 2018 at 2:42 AM, Ronald Tse <[email-masked]> wrote:
> It would be great to lock into a certain state — but as it is with
> publishing, the content can still change. A force push or a rebase could
> effectively remove that commit (hash) from the git repo.
>
> Don’t get me wrong, I’m all for allowing the addition of a commit hash, the
> more details provided the clearer to the reader. It’s just is not not a
> permanent reference, and hence not a silver bullet.
>
> Allow me to slightly rewind the discussion — what is the intention to cite
> git repositories (I assume that non-GitHub repositories like GitLab are also
> meant to be supported)?
>
> I’m going to quote from ISO 690, the international standard that provides
> bibliographic citation guidelines. Here are few relevant examples.
>
> (In bibliography, the “viewed: [date]” / “accessed: [date]" phrases are
> often used to indicate the uncertainty of the current content, and is
> accepted practice.)
>
> EXAMPLE 2      MOZILLA FOUNDATION. Mozilla Firefox [software]. Available
> from: https://www.mozilla.org/. Path: Download Firefox. [accessed
> 2017-06-27].
>
> (with commit)
> EXAMPLE4    Linux kernel. V3.16.3, commit
> b5cf3193759f7cd1cfbeef11f5cf067bbce22e55. [software]. Linus Torvalds, 2014.
> [created 2014-09-13T11:30:10-0700]. See also:
> https://en.wikipedia.org/wiki/Linux.
>
>
> EXAMPLE 5      INTERNATIONAL ISBN AGENCY. E-Books and ISBNs: a position
> paper and action points from the International ISBN Agency [online].
> [London]: International ISBN Agency, 2010. Available from:
> http://www.isbn.org/sites/default/files/images/isbn_agency_e-books_position_paper.pdf.
> [viewed 2012-02-06].
>
> (with archival link)
> EXAMPLE 6      Internet forum. Wikipedia: The Free Encyclopedia. 26 May
> 2017, 11:05. Available from: https://en.wikipedia.org/wiki/Internet_forum.
> [viewed 2017-06-01]. Archived copy available from:
> https://web.archive.org/web/20170702110010/http://en.wikipedia.org/wiki/Internet_forum.
> [viewed 2017-07-04].
>
> Hope this helps!
>
> Kind regards,
> Ron
>
> On Mar 9, 2018, at 3:10 PM, Eggert, Lars <[email-masked]> wrote:
>
> +1 on allowing hashes
>

---

From: Ronald Tse <[email-masked]>
Date: Sat, 10 Mar 2018 01:44:21 +0000

Thanks. I certainly support allowing inclusion of a hash (“a hash is better than no hash”) and hence provided the relevant examples. Agree with the case about deleting the repository — that was the point I was trying to make.

I’d like to clarify if the allowance is for all publicly accessible Git repositories, rather than specifically only about GitHub; it seems to me a level playing field is more desirable.

Ronald Tse
Ribose Inc.

On Mar 10, 2018, at 6:28 AM, Martin Thomson <[email-masked]<mailto:[email-masked]>> wrote:

On Sat, Mar 10, 2018 at 2:42 AM, Ronald Tse <[email-masked]<mailto:[email-masked]>> wrote:
It would be great to lock into a certain state — but as it is with
publishing, the content can still change. A force push or a rebase could
effectively remove that commit (hash) from the git repo.

1. If the intention is to cite computer software contained in the git repo,
ISO 690 gives these examples:

(no commit)

(with commit)

2. If the intention is to cite content provided by the git repo, the
relevant examples are:

(no archival link)

(with archival link)

Hope this helps!

Kind regards,
Ron

Ronald Tse
Ribose Inc.

+1 on allowing hashes

Hello all,

So:

OLD
[mpingSource]

NEW
[mpingSource]

Thanks!
Heather Flanagan, RSE

---

From: Martin Thomson <[email-masked]>
Date: Sun, 11 Mar 2018 09:17:28 +1100

No sense in limiting this to github.  bitbucket, gitlab, and others
are all likely reasonable choices.  No need to change the rules
though.  All the usage is similar, even if the page layout changes.

On Sat, Mar 10, 2018 at 12:44 PM, Ronald Tse <[email-masked]> wrote:
> Thanks. I certainly support allowing inclusion of a hash (“a hash is better
> than no hash”) and hence provided the relevant examples. Agree with the case
> about deleting the repository — that was the point I was trying to make.
>
> I’d like to clarify if the allowance is for all publicly accessible Git
> repositories, rather than specifically only about GitHub; it seems to me a
> level playing field is more desirable.
>
> On Mar 10, 2018, at 6:28 AM, Martin Thomson <[email-masked]>
> wrote:
>

---

From: Ronald Tse <[email-masked]>
Date: Sun, 11 Mar 2018 03:58:45 +0000

Thanks Martin, cannot agree more with you!

Ronald Tse
Ribose Inc.

> On Mar 11, 2018, at 6:17 AM, Martin Thomson <[email-masked]> wrote:
>

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 27 Mar 2018 05:46:42 -0700

Thank you, all, for your feedback. I strongly agree that we should be
targeting a reference format that applies to source code repositories in
general, acknowledging that GitHub is currently the leading favorite for
most. After further discussion within the RFC Editor, we're proposing
the following structure:

Proposed Guidance on referencing web-based public code repositories
(e.g., Github)

1) Should not appear as Normative References.

2) Format of reference entries:

authors — omit them

title — include if available (some judgement may be required on the part
of the editors and authors to have a sensible title)

commit hash — include if exists, short form preferred if available

date — use date of last commit at time doc is edited

URL — include URL to main page of repository

Examples:

[pysaml2]  "Python implementation of SAML2", commit 7135d53
<https://github.com/IdentityPython/pysaml2/commit/7135d5370425b5a0fb18ddd604779f6195fc3306>,
March 2018. <https://github.com/IdentityPython/pysaml2>.

[linuxlite] "Linux Lite", March 2018.
<https://sourceforge.net/projects/linuxlite/>
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: "Paul Hoffman" <[email-masked]>
Date: Tue, 27 Mar 2018 05:57:17 -0700

> URL — include URL to main page of repository

This makes sense. However, I'm unclear in the current tooling how to 
include the commit hash. It's not part of the title, nor is it an 
author.

--Paul Hoffman

---

From: Adam Roach <[email-masked]>
Date: Tue, 27 Mar 2018 07:58:58 -0500

In the case that there is no hash, can we at least include a day (and preferably a time)?

/a

> On Mar 27, 2018, at 07:46, Heather Flanagan (RFC Series Editor) <[email-masked]> wrote:
> 
> 
> 
> Thank you, all, for your feedback. I strongly agree that we should be targeting a reference format that applies to source code repositories in general, acknowledging that GitHub is currently the leading favorite for most. After further discussion within the RFC Editor, we're proposing the following structure:
> 
> 
> Proposed Guidance on referencing web-based public code repositories (e.g., Github) 
> 
> title — include if available (some judgement may be required on the part of the editors and authors to have a sensible title)
> 
> [pysaml2]  "Python implementation of SAML2", commit 7135d53, March 2018. <https://github.com/IdentityPython/pysaml2>.
> 
> [linuxlite] "Linux Lite", March 2018. <https://sourceforge.net/projects/linuxlite/>

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 27 Mar 2018 06:05:33 -0700

Hi Adam,

Are you thinking of something other than date of commit? Or are you
asking that we add hour/minute to that as well?

-Heather

On 3/27/18 5:58 AM, Adam Roach wrote:
> On Mar 27, 2018, at 07:46, Heather Flanagan (RFC Series Editor)
> <[email-masked] <mailto:[email-masked]>> wrote:
>
>>
>>
>> targeting a reference format that applies to source code repositories
>> in general, acknowledging that GitHub is currently the leading
>> favorite for most. After further discussion within the RFC Editor,
>> we're proposing the following structure:
>>
>>
>> title — include if available (some judgement may be required on the
>> part of the editors and authors to have a sensible title)
>>
>> [email-masked] <mailto:[email-masked]>

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 27 Mar 2018 06:06:08 -0700

On 3/27/18 5:57 AM, Paul Hoffman wrote:
> include the commit hash. It's not part of the title, nor is it an author.
>
> --Paul Hoffman 

True. We might need to add something to the vocabulary and adjust the
tooling accordingly.

-Heather

---

From: Adam Roach <[email-masked]>
Date: Tue, 27 Mar 2018 08:45:38 -0500

Really, we want to point to a specific version — that’s what a hash gets us. Lacking a specific unique identifier, the best we can hope for is time to the greatest precision available. Day, if you have it. Minutes, if available. Seconds, too. If the system provides sub-second resolution, include it. Anything that reduces that chances of the reference ambiguously referencing more than one version. 

/a

> On Mar 27, 2018, at 08:05, Heather Flanagan (RFC Series Editor) <[email-masked]> wrote:
> 
> Hi Adam,
> 
> Are you thinking of something other than date of commit? Or are you asking that we add hour/minute to that as well?
> 
> -Heather
>

---

From: Adam Roach <[email-masked]>
Date: Tue, 27 Mar 2018 08:47:57 -0500

It also occurs to me that SVN (as in your example) uses r-numbers instead of hashes to identify unique versions. Perhaps use those instead?

/a

> On Mar 27, 2018, at 08:45, Adam Roach <[email-masked]> wrote:
>

---

From: Jim Schaad <[email-masked]>
Date: Tue, 27 Mar 2018 07:18:52 -0700

It might be possible that one could also reference to a release marker which would be similar to referencing the commit.

Jim

From: rfc-interest <[email-masked]> On Behalf Of Adam Roach
Sent: Tuesday, March 27, 2018 6:46 AM
To: Heather Flanagan (RFC Series Editor) <[email-masked]>
Cc: [email-masked]
Subject: Re: [rfc-i] GitHub references

/a

On Mar 27, 2018, at 08:05, Heather Flanagan (RFC Series Editor) <[email-masked] <mailto:[email-masked]> > wrote:

Hi Adam,

-Heather

/a

On Mar 27, 2018, at 07:46, Heather Flanagan (RFC Series Editor) <[email-masked] <mailto:[email-masked]> > wrote:

authors — omit them 

Examples:

[pysaml2]  "Python implementation of SAML2", commit 7135d53 <https://github.com/IdentityPython/pysaml2/commit/7135d5370425b5a0fb18ddd604779f6195fc3306> , March 2018.  <https://github.com/IdentityPython/pysaml2> <https://github.com/IdentityPython/pysaml2>.

[linuxlite] "Linux Lite", March 2018.  <https://sourceforge.net/projects/linuxlite/> <https://sourceforge.net/projects/linuxlite/>

---

From: Martin J. Dürst <[email-masked]>
Date: Thu, 29 Mar 2018 16:11:07 +0900

> Really, we want to point to a specific version — that’s what a hash gets us. Lacking a specific unique identifier, the best we can hope for is time to the greatest precision available. Day, if you…

If we want to point to a precise version, then that's certainly the way 
to go. But there are cases where one may NOT want a precise version. 
Examples include stuff like "there's code over there that you might be 
able to use" or "use the newest version because it may have less (known) 
bugs than older ones", and so on.

At the W3C (long time ago), we went through this with respect to Unicode 
(which was at that time a book). In some cases, we wanted to cite a 
specific version. In other cases, we wanted to the newest version (with 
all the fancy new characters, which didn't included emoji at that time) 
to be usable.

Regards,   Martin.