Re: Recognising Contributions

[chris.j...@gmail.com]

Just to expand on my question a little bit with a comment, I think it would 
help to make the ticket corresponding to a release note easier to find 
because it would give people an easier way to answer the question, "what is 
the reasoning / background / discussion for this change?" Currently, there 
isn't really a convenient way to do this. One method that comes to mind is 
using git-blame on the source file corresponding to the release notes, and 
then clicking through to the commit, then PR, then ticket, but that method 
is roundabout and requiring several steps. Another might be searching the 
tracker for keywords, but that method can be hit-or-miss. To address the 
readability / "beauty" concern, maybe there's an even less obtrusive way to 
link to the ticket than including the ticket number after the sentence in 
parentheses (e.g. like adding a symbol after the final period that acts a 
hyperlink and/or making the hyperlink appear only on hover).

However, this is separate from the recognition issue, so perhaps off-topic 
for this thread.

--Chris


On Wednesday, August 18, 2021 at 3:22:17 PM UTC-4 timog...@gmail.com wrote:

> I started including ticket numbers in patch releases because there aren't 
> too many changes there and every change has a release note. I think the 
> ticket numbers are useful to quickly identify the cause of some change or 
> regression in a patch release where upgrades should generally be safer and 
> therefore may have less testing than with a major release upgrade.
>
> I think linking to tickets and/or mentioning authors in major releases 
> notes would detract from readability (but maybe just beauty), and of 
> course, not every commit (like bug fixes) in major releases requires a 
> release note.
>
> As an infrequent contributor these days, I'm not seeking any more 
> recognition from my contributions, nor would more recognition encourage me 
> to contribute more. I'd rather the Django team spend their efforts on 
> building software than on publicity.
> On Wednesday, August 18, 2021 at 2:20:25 PM UTC-4 chris.j...@gmail.com 
> wrote:
>
>> Related to this discussion, what's the current policy / practice around 
>> linking to tickets from the release notes? It looks the release notes for 
>> patch releases already link to tickets, e.g.
>> https://docs.djangoproject.com/en/dev/releases/3.2.6/
>>
>> However, for feature release, it looks like the tickets aren't linked to, 
>> e.g.
>> https://docs.djangoproject.com/en/dev/releases/3.2/
>> https://docs.djangoproject.com/en/dev/releases/4.0/
>>
>> Is the difference deliberate? Is it currently being done manually for 
>> patch releases -- is that why it's being done / can only be done there?
>>
>> --Chris
>>
>>
>> On Wednesday, August 18, 2021 at 3:37:21 AM UTC-4 carlton...@gmail.com 
>> wrote:
>>
>>> Hey David. 
>>>
>>> Thanks for the follow-up here. 
>>>
>>> I think at least for 4.0 we should focus on adding callouts/recognition 
>>> to the release blog post, rather than the release notes. 
>>>
>>> For one, release notes only contain new features, and we want to call 
>>> out all the different contributions that don’t fall under that. The bug 
>>> fixes, the docs changes, the translations teams, triage and review folks, 
>>> and so on… — there’s much more than just new features. It would be nice to 
>>> call out the new contributors (and the old too, but especially the new) — I 
>>> think we can (and have time) to pull together something good in the more 
>>> discursive format the release announcement allows. 
>>>
>>> For another, more narrowly practical point, I’d like a test-bed before 
>>> we change the release note process, which is part of our daily workflow. 
>>> Doing it in the release announcement is a one-shot opportunity to try ideas 
>>> and see how it goes. If there are elements we then want to bring into the 
>>> release notes going forward then that’s open. (But softly, softly… being 
>>> the thought.) 
>>>
>>> Kind Regards,
>>>
>>> Carlton
>>>
>>>
>>> On 18 Aug 2021, at 09:20, smi...@gmail.com  wrote:
>>>
>>> Hi All,
>>>
>>> Just coming back to this again (time flies), although we've got a while 
>>> until 4.0 is released so no rush here.
>>>
>>> I've got a few different thoughts here:
>>>
>>> *Data*
>>>
>>> I had a look at the various tools discussed above to see if any give us 
>>> what we need. While on that journey I came accross git's `shortlog`. 
>>> Apparently git use this to create their release notes, there's a few 
>>> options here but something like the following will give the list of 
>>> contributors (and number of commits) since 3.2.
>>>
>>> What I like about this is it "coalesce together commits by the same 
>>> person". The other tools above would have resulted in a number of different 
>>> entries for many folk as they use different email addresses (or their 
>>> GitHub "email" gets used). 
>>>
>>> $ git shortlog 3.2..main -n -s --group=author 
>>> --group=trailer:co-authored-by
>>>
>>> I'm not

Re: Recognising Contributions

[Tim Graham]

I started including ticket numbers in patch releases because there aren't 
too many changes there and every change has a release note. I think the 
ticket numbers are useful to quickly identify the cause of some change or 
regression in a patch release where upgrades should generally be safer and 
therefore may have less testing than with a major release upgrade.

I think linking to tickets and/or mentioning authors in major releases 
notes would detract from readability (but maybe just beauty), and of 
course, not every commit (like bug fixes) in major releases requires a 
release note.

As an infrequent contributor these days, I'm not seeking any more 
recognition from my contributions, nor would more recognition encourage me 
to contribute more. I'd rather the Django team spend their efforts on 
building software than on publicity.
On Wednesday, August 18, 2021 at 2:20:25 PM UTC-4 chris.j...@gmail.com 
wrote:

> Related to this discussion, what's the current policy / practice around 
> linking to tickets from the release notes? It looks the release notes for 
> patch releases already link to tickets, e.g.
> https://docs.djangoproject.com/en/dev/releases/3.2.6/
>
> However, for feature release, it looks like the tickets aren't linked to, 
> e.g.
> https://docs.djangoproject.com/en/dev/releases/3.2/
> https://docs.djangoproject.com/en/dev/releases/4.0/
>
> Is the difference deliberate? Is it currently being done manually for 
> patch releases -- is that why it's being done / can only be done there?
>
> --Chris
>
>
> On Wednesday, August 18, 2021 at 3:37:21 AM UTC-4 carlton...@gmail.com 
> wrote:
>
>> Hey David. 
>>
>> Thanks for the follow-up here. 
>>
>> I think at least for 4.0 we should focus on adding callouts/recognition 
>> to the release blog post, rather than the release notes. 
>>
>> For one, release notes only contain new features, and we want to call out 
>> all the different contributions that don’t fall under that. The bug fixes, 
>> the docs changes, the translations teams, triage and review folks, and so 
>> on… — there’s much more than just new features. It would be nice to call 
>> out the new contributors (and the old too, but especially the new) — I 
>> think we can (and have time) to pull together something good in the more 
>> discursive format the release announcement allows. 
>>
>> For another, more narrowly practical point, I’d like a test-bed before we 
>> change the release note process, which is part of our daily workflow. Doing 
>> it in the release announcement is a one-shot opportunity to try ideas and 
>> see how it goes. If there are elements we then want to bring into the 
>> release notes going forward then that’s open. (But softly, softly… being 
>> the thought.) 
>>
>> Kind Regards,
>>
>> Carlton
>>
>>
>> On 18 Aug 2021, at 09:20, smi...@gmail.com  wrote:
>>
>> Hi All,
>>
>> Just coming back to this again (time flies), although we've got a while 
>> until 4.0 is released so no rush here.
>>
>> I've got a few different thoughts here:
>>
>> *Data*
>>
>> I had a look at the various tools discussed above to see if any give us 
>> what we need. While on that journey I came accross git's `shortlog`. 
>> Apparently git use this to create their release notes, there's a few 
>> options here but something like the following will give the list of 
>> contributors (and number of commits) since 3.2.
>>
>> What I like about this is it "coalesce together commits by the same 
>> person". The other tools above would have resulted in a number of different 
>> entries for many folk as they use different email addresses (or their 
>> GitHub "email" gets used). 
>>
>> $ git shortlog 3.2..main -n -s --group=author 
>> --group=trailer:co-authored-by
>>
>> I'm not quite sure how git then get to new and returning users, but 
>> presumably that could be a fairly short script to work out the new names 
>> since 3.2. 
>>
>> *Release Notes*
>>
>> Adding names and tickets seemed to receive a positive response earlier in 
>> the year. So the question here, is what format? 
>>
>> Python uses a couple of different formats
>> 1)  :  : Patch by 
>> 2)  (Contributed by  in )
>>
>> I think the main thing is to choose something, does anyone have a 
>> preference, either one of the above styles or something different? (My vote 
>> would be for the second option above)
>>
>> [1] https://docs.python.org/3/whatsnew/changelog.html
>> [2] https://docs.python.org/3/whatsnew/3.8.html
>>
>> *Events*
>>
>> Responding to Tom's point above, I think we'd want to reach out to one of 
>> the organisers of an event to see if folk would be interested in exploring 
>> this further. It's far more complex than "just" adding some text to a 
>> release note. However, given that it's a gathering of Django folk it seems 
>> like an opportunity to do _something_. 
>>
>> While I've seen what recognition can look like at corporate events those 
>> tend to rely on being Exclusive (think VIP areas et al), rather than 
>> Inclusive. I s

Re: Recognising Contributions

[chris.j...@gmail.com]

Related to this discussion, what's the current policy / practice around 
linking to tickets from the release notes? It looks the release notes for 
patch releases already link to tickets, e.g.
https://docs.djangoproject.com/en/dev/releases/3.2.6/

However, for feature release, it looks like the tickets aren't linked to, 
e.g.
https://docs.djangoproject.com/en/dev/releases/3.2/
https://docs.djangoproject.com/en/dev/releases/4.0/

Is the difference deliberate? Is it currently being done manually for patch 
releases -- is that why it's being done / can only be done there?

--Chris


On Wednesday, August 18, 2021 at 3:37:21 AM UTC-4 carlton...@gmail.com 
wrote:

> Hey David. 
>
> Thanks for the follow-up here. 
>
> I think at least for 4.0 we should focus on adding callouts/recognition to 
> the release blog post, rather than the release notes. 
>
> For one, release notes only contain new features, and we want to call out 
> all the different contributions that don’t fall under that. The bug fixes, 
> the docs changes, the translations teams, triage and review folks, and so 
> on… — there’s much more than just new features. It would be nice to call 
> out the new contributors (and the old too, but especially the new) — I 
> think we can (and have time) to pull together something good in the more 
> discursive format the release announcement allows. 
>
> For another, more narrowly practical point, I’d like a test-bed before we 
> change the release note process, which is part of our daily workflow. Doing 
> it in the release announcement is a one-shot opportunity to try ideas and 
> see how it goes. If there are elements we then want to bring into the 
> release notes going forward then that’s open. (But softly, softly… being 
> the thought.) 
>
> Kind Regards,
>
> Carlton
>
>
> On 18 Aug 2021, at 09:20, smi...@gmail.com  wrote:
>
> Hi All,
>
> Just coming back to this again (time flies), although we've got a while 
> until 4.0 is released so no rush here.
>
> I've got a few different thoughts here:
>
> *Data*
>
> I had a look at the various tools discussed above to see if any give us 
> what we need. While on that journey I came accross git's `shortlog`. 
> Apparently git use this to create their release notes, there's a few 
> options here but something like the following will give the list of 
> contributors (and number of commits) since 3.2.
>
> What I like about this is it "coalesce together commits by the same 
> person". The other tools above would have resulted in a number of different 
> entries for many folk as they use different email addresses (or their 
> GitHub "email" gets used). 
>
> $ git shortlog 3.2..main -n -s --group=author 
> --group=trailer:co-authored-by
>
> I'm not quite sure how git then get to new and returning users, but 
> presumably that could be a fairly short script to work out the new names 
> since 3.2. 
>
> *Release Notes*
>
> Adding names and tickets seemed to receive a positive response earlier in 
> the year. So the question here, is what format? 
>
> Python uses a couple of different formats
> 1)  :  : Patch by 
> 2)  (Contributed by  in )
>
> I think the main thing is to choose something, does anyone have a 
> preference, either one of the above styles or something different? (My vote 
> would be for the second option above)
>
> [1] https://docs.python.org/3/whatsnew/changelog.html
> [2] https://docs.python.org/3/whatsnew/3.8.html
>
> *Events*
>
> Responding to Tom's point above, I think we'd want to reach out to one of 
> the organisers of an event to see if folk would be interested in exploring 
> this further. It's far more complex than "just" adding some text to a 
> release note. However, given that it's a gathering of Django folk it seems 
> like an opportunity to do _something_. 
>
> While I've seen what recognition can look like at corporate events those 
> tend to rely on being Exclusive (think VIP areas et al), rather than 
> Inclusive. I suspect for a Django conference/event we'd want to do 
> something quite different. 
>
> Kind Regards
>
> David
> On Wednesday, 7 July 2021 at 21:52:14 UTC+1 t...@carrick.eu wrote:
>
>> This is something I've been thinking about a bit as well.
>>
>> Mostly I think adding authors to the release notes is probably the best 
>> bang for buck in terms of recognition. This is what I was mostly thinking 
>> about myself. The release notes are (I believe) very widely read, 
>> especially in comparison with anything on GitHub.
>>
>> The other suggestions are, I think, good and worthwhile, but probably not 
>> as impactful.
>>
>> I am interested / curious about your last point. I think adding some 
>> recognition to in person events might be nice, but I'm not sure what it 
>> would look like in practice.
>>
>> Tom
>>
>> On Mon, 5 Jul 2021 at 17:38, 'Adam Johnson' via Django developers 
>> (Contributions to Django itself)  wrote:
>>
>>> I'm all for exposing names in more places.
>>>
>>> Linking through to PR's from the release notes would

Re: Recognising Contributions

[Carlton Gibson]

Hey David. 

Thanks for the follow-up here. 

I think at least for 4.0 we should focus on adding callouts/recognition to the 
release blog post, rather than the release notes. 

For one, release notes only contain new features, and we want to call out all 
the different contributions that don’t fall under that. The bug fixes, the docs 
changes, the translations teams, triage and review folks, and so on… — there’s 
much more than just new features. It would be nice to call out the new 
contributors (and the old too, but especially the new) — I think we can (and 
have time) to pull together something good in the more discursive format the 
release announcement allows. 

For another, more narrowly practical point, I’d like a test-bed before we 
change the release note process, which is part of our daily workflow. Doing it 
in the release announcement is a one-shot opportunity to try ideas and see how 
it goes. If there are elements we then want to bring into the release notes 
going forward then that’s open. (But softly, softly… being the thought.) 

Kind Regards,

Carlton


> On 18 Aug 2021, at 09:20, smi...@gmail.com  wrote:
> 
> Hi All,
> 
> Just coming back to this again (time flies), although we've got a while until 
> 4.0 is released so no rush here.
> 
> I've got a few different thoughts here:
> 
> Data
> 
> I had a look at the various tools discussed above to see if any give us what 
> we need. While on that journey I came accross git's `shortlog`. Apparently 
> git use this to create their release notes, there's a few options here but 
> something like the following will give the list of contributors (and number 
> of commits) since 3.2.
> 
> What I like about this is it "coalesce together commits by the same person". 
> The other tools above would have resulted in a number of different entries 
> for many folk as they use different email addresses (or their GitHub "email" 
> gets used). 
> 
> $ git shortlog 3.2..main -n -s --group=author --group=trailer:co-authored-by
> 
> I'm not quite sure how git then get to new and returning users, but 
> presumably that could be a fairly short script to work out the new names 
> since 3.2. 
> 
> Release Notes
> 
> Adding names and tickets seemed to receive a positive response earlier in the 
> year. So the question here, is what format? 
> 
> Python uses a couple of different formats
> 1)  :  : Patch by 
> 2)  (Contributed by  in )
> 
> I think the main thing is to choose something, does anyone have a preference, 
> either one of the above styles or something different? (My vote would be for 
> the second option above)
> 
> [1] https://docs.python.org/3/whatsnew/changelog.html 
> 
> [2] https://docs.python.org/3/whatsnew/3.8.html 
> 
> 
> Events
> 
> Responding to Tom's point above, I think we'd want to reach out to one of the 
> organisers of an event to see if folk would be interested in exploring this 
> further. It's far more complex than "just" adding some text to a release 
> note. However, given that it's a gathering of Django folk it seems like an 
> opportunity to do _something_. 
> 
> While I've seen what recognition can look like at corporate events those tend 
> to rely on being Exclusive (think VIP areas et al), rather than Inclusive. I 
> suspect for a Django conference/event we'd want to do something quite 
> different. 
> 
> Kind Regards
> 
> David
> On Wednesday, 7 July 2021 at 21:52:14 UTC+1 t...@carrick.eu 
>  wrote:
> This is something I've been thinking about a bit as well.
> 
> Mostly I think adding authors to the release notes is probably the best bang 
> for buck in terms of recognition. This is what I was mostly thinking about 
> myself. The release notes are (I believe) very widely read, especially in 
> comparison with anything on GitHub.
> 
> The other suggestions are, I think, good and worthwhile, but probably not as 
> impactful.
> 
> I am interested / curious about your last point. I think adding some 
> recognition to in person events might be nice, but I'm not sure what it would 
> look like in practice.
> 
> Tom
> 
> On Mon, 5 Jul 2021 at 17:38, 'Adam Johnson' via Django developers 
> (Contributions to Django itself)  > wrote:
> I'm all for exposing names in more places.
> 
> Linking through to PR's from the release notes would also be useful for 
> "pulling back the curtain" and making Django's code a bit less magical. Plus 
> it could help the workflow for current contributors.
> 
> On Mon, 5 Jul 2021 at 16:07, Tom Forbes  > wrote:
> Perhaps we could do this as part of a Sphinx plugin? Right now each entry in 
> the release notes is only implicitly tied to the pull request that adds it. 
> 
> If we could add some kind of pull request ID marker to the release note 
> entries we could create an inline link to the PR (which might be very useful 
> by itself) as well as using it derive a list of contributors for eac

Re: Recognising Contributions

[smi...@gmail.com]

Hi All,

Just coming back to this again (time flies), although we've got a while 
until 4.0 is released so no rush here.

I've got a few different thoughts here:

*Data*

I had a look at the various tools discussed above to see if any give us 
what we need. While on that journey I came accross git's `shortlog`. 
Apparently git use this to create their release notes, there's a few 
options here but something like the following will give the list of 
contributors (and number of commits) since 3.2.

What I like about this is it "coalesce together commits by the same 
person". The other tools above would have resulted in a number of different 
entries for many folk as they use different email addresses (or their 
GitHub "email" gets used). 

$ git shortlog 3.2..main -n -s --group=author --group=trailer:co-authored-by

I'm not quite sure how git then get to new and returning users, but 
presumably that could be a fairly short script to work out the new names 
since 3.2. 

*Release Notes*

Adding names and tickets seemed to receive a positive response earlier in 
the year. So the question here, is what format? 

Python uses a couple of different formats
1)  :  : Patch by 
2)  (Contributed by  in )

I think the main thing is to choose something, does anyone have a 
preference, either one of the above styles or something different? (My vote 
would be for the second option above)

[1] https://docs.python.org/3/whatsnew/changelog.html
[2] https://docs.python.org/3/whatsnew/3.8.html

*Events*

Responding to Tom's point above, I think we'd want to reach out to one of 
the organisers of an event to see if folk would be interested in exploring 
this further. It's far more complex than "just" adding some text to a 
release note. However, given that it's a gathering of Django folk it seems 
like an opportunity to do _something_. 

While I've seen what recognition can look like at corporate events those 
tend to rely on being Exclusive (think VIP areas et al), rather than 
Inclusive. I suspect for a Django conference/event we'd want to do 
something quite different. 

Kind Regards

David
On Wednesday, 7 July 2021 at 21:52:14 UTC+1 t...@carrick.eu wrote:

> This is something I've been thinking about a bit as well.
>
> Mostly I think adding authors to the release notes is probably the best 
> bang for buck in terms of recognition. This is what I was mostly thinking 
> about myself. The release notes are (I believe) very widely read, 
> especially in comparison with anything on GitHub.
>
> The other suggestions are, I think, good and worthwhile, but probably not 
> as impactful.
>
> I am interested / curious about your last point. I think adding some 
> recognition to in person events might be nice, but I'm not sure what it 
> would look like in practice.
>
> Tom
>
> On Mon, 5 Jul 2021 at 17:38, 'Adam Johnson' via Django developers 
> (Contributions to Django itself)  wrote:
>
>> I'm all for exposing names in more places.
>>
>> Linking through to PR's from the release notes would also be useful for 
>> "pulling back the curtain" and making Django's code a bit less magical. 
>> Plus it could help the workflow for current contributors.
>>
>> On Mon, 5 Jul 2021 at 16:07, Tom Forbes  wrote:
>>
>>> Perhaps we could do this as part of a Sphinx plugin? Right now each 
>>> entry in the release notes is only implicitly tied to the pull request that 
>>> adds it. 
>>>
>>> If we could add some kind of pull request ID marker to the release note 
>>> entries we could create an inline link to the PR (which might be very 
>>> useful by itself) as well as using it derive a list of contributors for 
>>> each release.
>>>
>>> Tom
>>>
>>> On Wed, 30 Jun 2021 at 09:16, Carlton Gibson  
>>> wrote:
>>>
 Hi David, 

 Thanks for this. Yes. 

 Let's assume the 2020-2021 time filter is in place. 

 Mariusz recently picked up James' PR to add the list of Core 
 Contributors (back) to the website, which is/was part of the DEP 10 
 governance changes. 
 https://github.com/django/djangoproject.com/pull/1099

 The hope is that the DSF Board will approve that in their next meeting, 
 and we can get it live. With hindsight we perhaps could have moved quicker 
 but, the idea was to move on from there to recognise current and new 
 contributors on a more ongoing basis too. 

 So... my hope was to probably do something per-major release — so 3.2, 
 4.0, 4.1, etc. (Maybe we could do it every month but...) 

 * Who were the contributors? 
 * Who were the new contributors?(Special callout)
 * Who was on the Triage and Review team? ('cause it ain't just code)
 * And, can we identify other folks to call out...? (T&R team was an 
 attempt to capture participation here.) 

 I think Simon's github-to-sqlite tool is a good candidate. 
 Some others I've collected whilst this has been bubbling on the 
 low-ring: 

 * Katie McLaughlin provided some git lo