[rfc-i] GitHub references

Martin Thomson martin.thomson at gmail.com
Fri Mar 9 14:28:23 PST 2018


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 <tse at ribose.com> 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.)
>
> 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 <lars at netapp.com> wrote:
>
> +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 <martin.thomson at gmail.com> wrote:
>
> 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.
>
> On Fri, Mar 9, 2018 at 6:59 AM, Heather Flanagan (RFC Series Editor)
> <rse at rfc-editor.org> wrote:
>
>
> 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
> rfc-interest at rfc-editor.org
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest
>
> _______________________________________________
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest
>
> _______________________________________________
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest
>
>
>
> _______________________________________________
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest
>


More information about the rfc-interest mailing list