MRG, STY: Highlight new contributors [skip travis]

[larsoner]

1. Adds [ci skip] and [skip github] support to our GitHub CI
2. Moves new contributor lines to the top, selected by looking at names.inc in this diff
3. Bolds new contributor names
4. Moves new contributor changes to the top of each section
5. Renames "changelog / bug / API" to "enhancements / bugs / API changes" as these are more human-readable

[larsoner]

Bolding the entire lines did not look good, so I changed to bolding the names and moving to the top:

https://22353-1301584-gh.circle-artifacts.com/0/dev/whats_new.html

[agramfort]

how do other projects do it?

scipy puts a * next to the name in the list of contributors.

Can we just copy?

[larsoner]

We don't have a contributor list so we can't copy that. We could copy it for the release notes, though. @hoechenberger @cbrnr @sappelhoff @drammock were commenting over in #8150, WDYT?

[hoechenberger]

Personally I would simply do it sth like this:

What’s new

Current (0.21.dev0)

123 people have contributed code or documentation to this release. Of these, the following X were first-time contributors:

• Firsty Firstman
• Secondy Secondwoman
• Thirdy Whatever

❤️ We're grateful to all contributors! ❤️

Enhancements 🚀

• foo by bar
• baz by xxx

Bugs 🐜 (should ideally be "Bug Fixes"?!)

• foo by bar
• baz by xxx

API changes 🧐 (should ideally come BEFORE Bug Fixes??)

• foo by bar
• baz by xxx

[larsoner]

123 people have contributed code or documentation to this release.

The problem with this is that it's going to be a pain to keep up to date. We have to ask people to check to see if they have contributed yet and if not, then update the number. And then there will be even more merge conflicts. So I'd rather not add this part. This seems like a final at-relase-time release notes thing.

The "new contributors" section by contrast is pretty easy to update on the fly (at least until we get tens or hundreds of new contributors per release :) )

Otherwise I'm happy with @hoechenberger's proposal and can implement it if others agree

[hoechenberger]

123 people have contributed code or documentation to this release.

The problem with this is that it's going to be a pain to keep up to date. We have to ask people to check to see if they have contributed yet and if not, then update the number. And then there will be even more merge conflicts. So I'd rather not add this part. This seems like a final at-relase-time release notes thing.

The "new contributors" section by contrast is pretty easy to update on the fly (at least until we get tens or hundreds of new contributors per release :) )

Ohhh ok I wasn't aware of this distinction, I was actually only thinking about "making a changelog for a release".

Do you think we could include these metrics when we actually cut the release? :)

Otherwise I'm happy with @hoechenberger's proposal and can implement it if others agree

Thanks! I've edited my comment a couple minutes ago to add more colors (yes, colors!) i.e. emojis ;) Not sure if you've seen that! 😅

[agramfort]

I know we tend to all have egos but I would not put the names first. People looking at the doc should see the most important things. ym 2c

[larsoner]

Do you think we could include these metrics when we actually cut the release? :)

Yes we always do this, see step (5):

https://github.com/mne-tools/mne-python/wiki/How-to-make-a-release

[larsoner]

I know we tend to all have egos but I would not put the names first.

A compromise solution then is to do something like bold their name in the latest.inc document...

[hoechenberger]

I know we tend to all have egos but I would not put the names first.
People looking at the doc
should see the most important things.

ym 2c

I do agree, yet I think it's a bit of a tradeoff. We want to incentivise contributions by new developers in particular, and I think putting their name in a prominent place could really provide some motivational boost :) esp. since our release cycle is relatively long (i.e. it may take half a year until you "actually" get acknowledged by appearing in the "stable" changelog)

Maybe a compromise could be to add some kind of navigation / TOC that helps you jump to the desired section(s) immediately? I always missed something like that anyway!

[agramfort]

putting in bold the names of new contributors in the list sounds a good idea

[drammock]

I like the way @larsoner's bolding of "first time contributor Name Surname" looks in the changelog, but what I don't like is that some are right up top (enhancements) while others are at the top of later sections (bug, API) so they're offscreen / not as prominent. At the same time, I think I agree with @agramfort that having a special section for just the names seems to foreground the people over the code changes a bit too strongly. What about doing away with the separate sections for bug/api/enh, and having a color-coded tag (or emoji?) on each change indicating what kind of change it is, and then sorting the whole list (as @larsoner has done per-section) to put new contributors at the top?

[larsoner]

So something like this? :)

https://22353-1301584-gh.circle-artifacts.com/0/dev/whats_new.html

Then we also bold them once we make the names list for the release. It seems easy to maintain and helps keep them prominent

[agramfort]

do what you find best

…

[larsoner]

What about doing away with the separate sections for bug/api/enh, and having a color-coded tag (or emoji?) on each change indicating what kind of change it is

IMO the most important feature/distinction in the list of changes is the type of change: BUG means "things change immediately when you run your code, hopefully for the better", API means "things will change soon, change your code" and enhancement means "use this if you want but you don't need to worry about it". So people's attention levels to these lists should change accordingly. It's hard for me to see how you could still make this the most salient feature, even with emoji / colors / etc., and even if you can, it hurts readability if you are looking for "changes of X type", which I imagine is common.

This is probably the information that people want access to when looking at these lists, so it would be unfortunate to make it less usable to them in pursuit of giving better credit to new contributors.

But feel free to give it a shot and see if you can come up with something that stays readable. I guess in theory we could go fancy JavaScript and allow people to hide/show entries of a certain type with buttons or something. But this then starts to sound complicated and hard to maintain...

So my vote is still for bolding (and putting at the top of each section) the new ones, and bolding names in the alphabetical release notes list.

[hoechenberger]

What about doing away with the separate sections for bug/api/enh, and having a color-coded tag (or emoji?) on each change indicating what kind of change it is, and then sorting the whole list (as @larsoner has done per-section) to put new contributors at the top?

Re color codes I would be -1, re emojis I would be +5 :-)

🚀 – Enhancement
🐜 – Bug Fix
🧐 – API Change
🥇 – First-Time Contributor

- 🚀🥇 Speed up reading of annotations in EDF+ files by new contributor Jeroen Van Der Donckt
- 🚀 Add head to mri and mri to voxel space transform details to Source alignment and coordinate frames tutorial, by Alex Rockhill
- 🐜 🥇 Fix bug by adding error message when trying to save complex stc data in a non.-h5 format mne.VolSourceEstimate.save() by new contributor Lau Møller Andersen
- 🐜 🥇 Fix bug with logging in mne.io.Raw.set_eeg_reference() and related functions by new contributor Simeon Wong
- 🧐 The default argument meg=True in mne.pick_types() will change to meg=False in version 0.22 by Clemens Brunner

[drammock]

the most important feature/distinction in the list of changes is the type of change

yeah, OK. I find that convincing. But

BUG means "things change immediately when you run your code, hopefully for the better", API means "things will change soon, change your code" and enhancement means "use this if you want but you don't need to worry about it"

seems to imply that Bugfixes should come first and Enhancements should come last? Regardless, here's where I stand on the bigger-picture issue:

• bolding names of new contributors in the ongoing what's new page is good
• sorting within each what's new section to put new contributors at the top is good
• collapsing all sections is probably bad
• adding a tally to the release notes that breaks out numbers for all contributors vs new contributors is good
• maintaining the bolding of names in the release notes is good
• adding a separate section just listing new contrib. names separate from their contributions... @agramfort seems to think it sends the wrong message ("people looking at the docs should see the most important things") but maybe he meant for what's new page, rather than the release notes announcement? I think I agree it doesn't quite make sense for the ongoing what's new page, but I also think that we get to decide what is important, and I think honoring and encouraging new volunteers is important. Moreover, a sentence saying "we are grateful to all our new contributors this release cycle" and then listing the ~15-20 names (can be comma separated rather than one per line) is really not taking up that much space given how long the release notes usually are (see the last release notes here).

[hoechenberger]

See how Pandas does it:

https://pandas.pydata.org/docs/whatsnew/v1.1.2.html

[larsoner]

Seems to be essentially the same as scipy, add a character by their name in the list. I think we can do more than this.

[jona-sassenhagen]

Good to see this :)

[larsoner]

Is this PR a good enough step for 0.21? And we can do more extensive refactoring during the 0.22 cycle @drammock @hoechenberger ?

[drammock]

Changes look good but for some reason there are asterisks showing up in the second item here: https://22353-1301584-gh.circle-artifacts.com/0/dev/whats_new.html

[larsoner]

It's just an old rendering. Let's merge and see if it's better :)