[rfc-i] GitHub references

Ronald Tse tse at ribose.com
Fri Mar 9 17:44:21 PST 2018


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 <martin.thomson at gmail.com<mailto:martin.thomson at gmail.com>> wrote:

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<mailto: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<mailto: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<mailto: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<mailto: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<mailto: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


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.rfc-editor.org/pipermail/rfc-interest/attachments/20180310/ddc7caf0/attachment-0001.html>


More information about the rfc-interest mailing list