Recognising Contributions

[smi...@gmail.com]

Hi all,

I've had this sat in my drafts for a while. Rather than let it sit on the shelf any longer I thought it better to share. 

I've been thinking about recognising contributions recently. The main issue with the notes here is that it focuses on code rather than contributions to the wider Django ecosystem. However, if there are improvements that we could make here I think we should explore those, and maybe some of them could be used more widely.  

Here are a few ideas of how contributions could be recognise following a peer review of other projects. Some are better than others, some are easier to implement than others. Hopefully something to prompt some discussion. What do folk think? How would you feel if you were recognised in one of these ways?

- Add Python style `contributed by` in the release notes. I'm not so sure about adding the ticket number (in fact I think I saw Nick Pope point to something today that says we don't ref tickets?). [1]

- For the headline features add names to the blog post [2]. Could also add link to their blog / website /Twitter (less sure about this second part).

- The blog post (or another page) to include a long list of names of everyone who contributeted a commit in that release. I think it's fine if this is long, can probably use Simon W's GitHub-to-sqlite repo for this so it is sustainable. [3]

- For the headline features make a series of Twitter posts highlighting them and acknowledge contributors. I'm thinking something along the lines of what Adam Johnson did for the 3.2 release but include names & thank yous. 

- A rust style thanks page [4] (but **not** the all time list, I don't think that's helpful and it's on GitHub anyway).

- A go style contributor summit. (I don't think this is feasible, even remotely. But I'll put it out there!). A slight variation on this could be folk who have contributed could apply for different coloured conference passes/lanyards.  [5]

Kind Regards

David

[1]https://docs.python.org/3/whatsnew/3.8.html
[2]https://www.djangoproject.com/weblog/2021/apr/06/django-32-released/
[3]https://github.com/dogsheep/github-to-sqlite
[4]https://thanks.rust-lang.org/
[5]https://blog.golang.org/contributors-summit-2019

[Carlton Gibson]

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 log pointers https://glasnt.com/blog/script-o-hatrack/

* See also https://github.com/LABHR/octohatrack

* GitHub built this based on Simon's ideas: https://octo.github.com/projects/flat-data

* "A git query language" https://github.com/filhodanuvem/gitql

* "git quick stats" https://github.com/arzzen/git-quick-stats

I think there's plenty of tooling there to show how to get the info we want. 

At a guess it's a couple of evenings exploring, and then pulling it into a report. 

I think if we were to do something along these lines, starting a new tradition, for Django 4.0 in December, that would be really great. 

I'm not sure as yet on the exact format to present all that. 

The blog post for the _Final_ versions could say more without too much difficulty. 

(e.g. https://www.djangoproject.com/weblog/2021/apr/06/django-32-released/ ) 

Kind Regards,

Carlton

[Tom Forbes]

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

--
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/0174cb33-44e3-48f4-80dc-27b8f9fb8cb4n%40googlegroups.com.

[Adam Johnson]

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.

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAFNZOJNob_gXZAVWHBoW2MF18%2B8sxEJQYMCuXZj8%2BBB_910U8w%40mail.gmail.com.

[Tom Carrick]

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

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAMyDDM0Zh60Bz9qkr9mEMOcP67wxYxXQ7d7g0t0n%3DPPR6ay4YQ%40mail.gmail.com.

[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) <Link to Ticket> : <Description> : Patch by <Name>

2) <Description> (Contributed by <Name> in <Ticket>)

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

[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

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/3eb98e48-d08e-4364-bc02-bc6b987d3cdan%40googlegroups.com.

[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

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

[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

[Carlton Gibson]

Hey Tim.

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

Recognising contributions, in the many forms that they take, is about the

sustainability of the project.

We have a maintainership problem — it's OK now, but there's no depth to it.

We have a diversity of maintainership problem, in that the profile of regular

contributors doesn't match that of the user-base as a whole. 

There's much writing on the life-cycle of projects, and how they can either

open out to the community, or turn in on themselves and wither and die. (See

e.g. Nadia Eghbal's Working in Public for a good entry point.)

There's a whole host of inter-related points here but, providing recognition of

contributions give public validation that helps those who aren't economically

privileged enough to spend many hours on open source just for the intrinsic

reward of it — it can help people get jobs. It also helps us to identify the

hidden work that's done, so hopefully we can make that more sustainable. If we

can highlight the contributions from the community that's, hopefully, a little

more diverse than it looks like on the surface.

To make an effort to call-out contributors, especially those just starting out, 

is a small thing we can do. 

Kind Regards,

Carlton