Re: Set up autolinks on Django's GitHub repositories

2020-08-03 Thread 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

On Monday, 3 August 2020 at 14:52:31 UTC+7 in...@markusholtermann.eu wrote:

> 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>.
>  
>
>

-- 
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-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/5f2fb712-a0eb-49c4-a368-2c01adeec8e1n%40googlegroups.com.

Re: Set up autolinks on Django's GitHub repositories

2020-08-03 Thread 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-developers+unsubscr...@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
>  
> .

-- 
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-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/0f9ddf24-b903-4bf1-9b27-bc73353b1957%40www.fastmail.com.

Set up autolinks on Django's GitHub repositories

2020-08-02 Thread 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

-- 
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-developers+unsubscr...@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.