Referencing commits

[jebob]

The docs state

Please reference the relevant GitHub issues in your commit message using GH1234 or #1234. Either style is fine, but the former is generally preferred

But out of the most recent commits, a majority uses the latter style and a minority use gh-1234. Has the advice changed?

[gfyoung]

Excellent question! The advice has not changed AFAIK, though we have not generally enforced it too heavily. Case in point, I am (the only) member who uses the "gh" convention, and I'm a core-committer 😄

[gfyoung]

The reason why we would prefer to prefix commit references with "GH" (or "gh-") is because it is clearer that this issue / PR was filed on GitHub and not some other hosting platform. Using the "#" is ambiguous.

That being said, the reason why I use "gh-" is because it receives special parsing from GitHub so that you can navigate to the actual issue / PR directly, which doesn't happen with "GH." The special parsing also happens when you use "#".

I thus find "gh-" to be the best of both worlds in terms of clarity and special parsing 😄

[gfyoung]

@jebob : I'm closing this for now since we have been able to address your question (hopefully), but let me know if you would like me to elaborate OR would like to update the docs, and I can reopen this.

[jebob]

Thanks!