[rfc-i] GitHub references

Ronald Tse tse at ribose.com
Sat Mar 10 19:58:45 PST 2018


Thanks Martin, cannot agree more with you!

_____________________________________

Ronald Tse
Ribose Inc.

> On Mar 11, 2018, at 6:17 AM, Martin Thomson <martin.thomson at gmail.com> wrote:
> 
> 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 <tse at ribose.com> 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.
>> 
>> _____________________________________
>> 
>> Ronald Tse
>> Ribose Inc.
>> 
>> 
>> On Mar 10, 2018, at 6:28 AM, Martin Thomson <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> 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
>> 
>> 
>> 
>> _______________________________________________
>> 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