Set up autolinks on Django's GitHub repositories

[laym...@gmail.com]

Hi folks,

I came across this feature on GitHub today:

https://docs.github.com/en/github/administering-a-repository/configuring-autolinks-to-reference-external-resources

In short, it adds autolinks to external resources (e.g. our issue tracker) by referencing them using a prefix in GitHub comments or commits. So, instead of using Markdown to manually link to a ticket, we can just use the prefix followed by the ticket number, e.g. TR-123 and GitHub will automatically convert it to a link.

Currently, we use the # character as a convention to refer to the tickets. However, this conflicts with the use of # on GitHub which automatically links to PRs (and issues if enabled). As a result, commits that refer to a ticket whose number is also a valid PR number, incorrectly link to the PR. Here's an example: https://github.com/django/django/commit/5d4b9c1cab03f0d057f0c7751862df0302c65cf9

As you can see, the commit message links to PR#12990 which actually isn't relevant. This also generates noise in the PR itself: https://github.com/django/django/pull/12990. I think that can be misleading to new contributors.

By using the autolinks, we can properly link the reference to the tickets. Sadly, we can't replace GitHub's # autolinks. So, we need to create a new prefix. This has some downsides, though:

• It breaks the current convention of using # to refer to tickets.
• The prefix must only contain letters, numbers, or -:/#
  
• The prefix is 3 characters minimum, so this means commit messages will be at least 2 characters longer than with the current convention.
  

However, considering the benefits:

• No more incorrect links to irrelevant PRs.
• No more noise in PRs from irrelevant commits.
• Clickable ticket numbers in commits that take you to the tickets.
• Quick linking to tickets in GitHub comments (no need to use Markdown).
• Less confusion to new contributors.

I think it's worth it.

What do y'all think? If we're to agree upon this, I guess we need to come up with the prefix. I don't have any preference; as long as it makes sense, I'm in.

Oh, and one more thing: maybe we can also set up a prefix for PRs to easily differentiate between the two from now on. Here are some proposals:

• TR-1234 for TRac tickets, and PR-5678 for PRs.
• TR#1234 for TRac tickets, and PR#5678 for PRs.

And maybe we can set up another for DEPs, but that may not be necessary...

Regards,

Sage

[Markus Holtermann]

Hi Sage,

thank you for the suggestion. There's already autolinking setup for `ticket-123`. I'm happy to add another one which would be a bit briefer. But if this is done, the contribution documentation needs to be updated as well.

/Markus

On Mon, Aug 3, 2020, at 8:06 AM, laym...@gmail.com wrote:
> Hi folks,
>
> I came across this feature on GitHub today:
> https://docs.github.com/en/github/administering-a-repository/configuring-autolinks-to-reference-external-resources
>
> In short, it adds autolinks to external resources (e.g. our issue
> tracker) by referencing them using a prefix in GitHub comments or
> commits. So, instead of using Markdown to manually link to a ticket, we

> can just use the prefix followed by the ticket number, e.g. *TR-123*

> and GitHub will automatically convert it to a link.
>
> Currently, we use the # character as a convention to refer to the
> tickets. However, this conflicts with the use of # on GitHub which
> automatically links to PRs (and issues if enabled). As a result,
> commits that refer to a ticket whose number is also a valid PR number,
> incorrectly link to the PR. Here's an example:
> https://github.com/django/django/commit/5d4b9c1cab03f0d057f0c7751862df0302c65cf9
>
> As you can see, the commit message links to PR#12990 which actually
> isn't relevant. This also generates noise in the PR itself:
> https://github.com/django/django/pull/12990. I think that can be
> misleading to new contributors.
>
> By using the autolinks, we can properly link the reference to the
> tickets. Sadly, we can't replace GitHub's # autolinks. So, we need to
> create a new prefix. This has some downsides, though:

> * It breaks the current convention of using # to refer to tickets.
> * The prefix must only contain letters, numbers, or -:/#
> * The prefix is 3 characters minimum, so this means commit messages

> will be at least 2 characters longer than with the current convention.
> However, considering the benefits:

> * No more incorrect links to irrelevant PRs.
> * No more noise in PRs from irrelevant commits.
> * Clickable ticket numbers in commits that take you to the tickets.
> * Quick linking to tickets in GitHub comments (no need to use
> Markdown).
> * Less confusion to new contributors.

> I think it's worth it.
>
> What do y'all think? If we're to agree upon this, I guess we need to
> come up with the prefix. I don't have any preference; as long as it
> makes sense, I'm in.
>
> Oh, and one more thing: maybe we can also set up a prefix for PRs to
> easily differentiate between the two from now on. Here are some
> proposals:

> * *TR-1234* for TRac tickets, and *PR-5678* for PRs.
> * *TR#1234* for TRac tickets, and *PR#5678* for PRs.

> And maybe we can set up another for DEPs, but that may not be
> necessary...
>
> Regards,
> Sage
>

> --
> You received this message because you are subscribed to the Google
> Groups "Django developers (Contributions to Django itself)" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to django-develop...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/django-developers/e070dd97-0d22-4566-a605-867141f7e0aan%40googlegroups.com <https://groups.google.com/d/msgid/django-developers/e070dd97-0d22-4566-a605-867141f7e0aan%40googlegroups.com?utm_medium=email&utm_source=footer>.

[laym...@gmail.com]

Hi Markus,

Thanks, I must've missed that 😅. Then, I guess I'd suggest adding a briefer one and using it in commit messages. So yep, the contributing guide needs to be updated as well. However, this changes the convention which has been there for years. I'd like to hear what the Fellows or board think about this.

Sage