[rfc-i] GitHub references

Martin J. Dürst duerst at it.aoyama.ac.jp
Thu Mar 8 21:25:28 PST 2018


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.

On 2018/03/09 09:16, Martin Thomson 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


More information about the rfc-interest mailing list