Add history to readme

[saulshanabrook]

I have written up a short history of the contributors of this extension on the README. It is meant as an example of one way we could highlight the different companies, organizations, and people who have contributed to this extension. Instead of just putting a number of names and organizations in the README, I thought a narrative history might let us bring more subtlety to the process.

I am sure it is incomplete and might be inaccurate in places, I tried to do my best from my personal knowledge and from the contributors list on Github. I tried to include people who had regular commits to this repository for some amount of time.

Please give feedback here on both the particulars of the text and whether you think generally something like this makes sense.

[meeseeksmachine]

This pull request has been mentioned on Jupyter Community Forum. There might be relevant details there:

https://discourse.jupyter.org/t/ideas-for-recognizing-developer-contributions-by-companies-institutes/3178/2

[saulshanabrook]

I brought this up at the JupyterLab dev meeting today and it was received positively. cc @jaipreet-s @neelamgehlot @ktaletsk @fcollonval if you all could glance over this and let me know if it seems accurate from your perspective, that would be great!

[jasongrout]

The current contributor list lists 37 people who have contributed to the project. Can you include a note acknowledging other contributors, perhaps like "Many others have contributed as well. See the git logs for more details." or something? Also, @saulshanabrook you are listed as a top contributor, but are not listed in this acknowledgement by name.

Is there a commitment to keep the file up to date over time? This sort of thing can quickly fall out of date, which is why I prefer statements like this to be tied to releases, like an acknowledgement in a changelog or release announcement (and such changelogs or release announcements can and should be stored in the repo, I think). Then the acknowledgement is a snapshot in time, like:

in the 2.0 release, we'd like to thank this list of contributors, including these people who contributed for the first time. We'd also like to especially thank contributors X (who contributed significantly towards A, sponsored by B), and Y (who worked a lot on C sponsored by D).

Then the acknowledgement is a snapshot in time, does not need to be updated, and both rewards continual contribution (for example a significant sponsor or contributor gets mentioned time and time again in the release notes, each time for specific improvements) and also especially encourages first-time contributions to grow the contributor base.

[jasongrout]

There was once an open-source project which had regular releases and explicitly acknowledged each person who contributed to that release. It was a nice motivation to continually contribute to the project - if there was a release coming up and I had been too busy to contribute for a while, it was a fun goal to try to find at least one issue that I could fix each release, sort of like having a streak of mentions in the release notes. And as we all know, often fixing one issue leads to another, and another, etc.

[saulshanabrook]

Thank you @jasongrout for all the comments.

Also, @saulshanabrook you are listed as a top contributor, but are not listed in this acknowledgement by name.

Done.

Can you include a note acknowledging other contributors, perhaps like "Many others have contributed as well. See the git logs for more details." or something?

Done. I also added an acknowledgement to this other OS projects this relies on

Is there a commitment to keep the file up to date over time? This sort of thing can quickly fall out of date, which is why I prefer statements like this to be tied to releases, like an acknowledgement in a changelog or release announcement (and such changelogs or release announcements can and should be stored in the repo, I think),

I added a "accurate as of..." message and an instruction to update after each release. This will fall out of date, but I actually think it has some advantages over the current source of this information, which is sort of the "Team" section, which lists current maintainers. At least with history, you don't have to go and edit the past, you can just add to the end. However with maintainers, I notice it's not only not up to date, its inaccurate (for example I don't really maintain that package at the moment).

it was a fun goal to try to find at least one issue that I could fix each release, sort of like having a streak of mentions in the release notes

I agree! I think that's also a nice thing for a project to do, but I think this serves a slightly different purpose by signalling in a more accessible way who (companies and ppl) has driven this project forward, possibly as marketing for them and also as an indicator of the robustness of the software (since many different people all chose to work on it).

---

One remaining issue is the duplication between this and the current "Team" section. Not sure what to do about that.

[saulshanabrook]

I removed the Quansight references, since it was only the pass through org not the originator of funds, as suggested by @betatim and included Brian Granger because he also listed as part of the team.

This is ready for review!

[fcollonval]

LGTM ! Thanks @saulshanabrook

[saulshanabrook]

I just pushed a switch from "History" to "attributions" as suggested by @kgryte, so it will be easier to keep up to date. @fcollonval what do you think now?

[mlucool]

It seems cleaner, but I want to note the following issues, which may be acceptable:

1. No way to highlight relative commitment to the project. I.e. someone sponsoring this in a big way or a simple feature. It also conflates one time sponsorship vs. continued support. In the previous long form style, descriptions attenuated this.
2. If a person contributed without a company, how would they be listed?

[saulshanabrook]

No way to highlight relative commitment to the project. I.e. someone sponsoring this in a big way or a simple feature. It also conflates one time sponsorship vs. continued support. In the previous long form style, descriptions attenuated this.

This is true... Not sure we have any articulated classifications in place here for Jupyter as a whole....

If a person contributed without a company, how would they be listed?

They could be listed on a line by themselves without a company name, we would just have to change the header to be "organizations or individuals"

[saulshanabrook]

Notes from jlab meeting:

• @afshin: Seems like a good start, we can always add more nuance here between levels of support at a later date if we wish.
• @jasongrout: Changelog based recognition. For example in VS Code, this blog post calls out to bloomberg in a large way.
  • In our case the changelog isn't as well read, especially for an extension
• @telamonian: How to distinguish between Max as DE Shaw funded and Max as own person now.

Not sure how this would affect JupyterLab core, if we adopted a similar system there.

---

A proposal that came out at the was to make the "Sponsorships" and "Contributors" sections separate. They have different aims, Sponsorships is for organizations and Contributors is for individuals.

We currently have a "Team" section but it isn't that up to date and generally we have less people in the "Team" than have actively contributed. One option would be to use this project and bot to keep a larger Contributors sections: https://github.com/all-contributors/all-contributors

Then for the Sponsorship section we just list companies, not any individuals. Maybe even do logos? That way we don't get in to the spot Max is in where he did work for DE Shaw, but is now not with DE Shaw. So DE Shaw would show up under Sponsors, and Max would show under contributors.

Thoughts?

[saulshanabrook]

I am testing out using the all-contributors format and bot:

@all-contributors please add @saulshanabrook for code, review, and project management

[allcontributors]

@saulshanabrook

I've put up a pull request to add @saulshanabrook! 🎉

[saulshanabrook]

OK that PR looks good, but I would like to see if I can add all the changes to this PR so they can be reviewed together with documentation on how to add people to the list. I am going to try using the CLI for that.

[saulshanabrook]

OK this is now good to go again from my end. I tried to roughly add people's existing contribution areas, but we can easily tweak them if this PR is merged using the bot or the CLI.

I merged the supporting institutions in with the people, the difference being they contribute financial benefits whereas people contribute in other areas.

I also removed our existing "Team" section because it is out of date and overlaps with this new one.

[mlucool]

I tried to roughly add people's existing contribution areas, but we can easily tweak them if this PR is merged using the bot or the CLI.

Does everyone who makes a PR become a contributor? If so, I find that buries the signal in the noise when projects have done that. There should be some community agreement to make the front page of the project. I find the all contributors project page hard to figure out who is active and key to this project. When I look here, it clearly just a couple of key people.

I don't love the money icon for sponsors - it looks crude and seems to not reflect that sponsorship of OSS is more of a relationship than a transaction. What about an icon like this (not OSI approved, but the idea is its a relationship). I guess the problem would then be diverging from https://allcontributors.org/docs/en/emoji-key.

Can we separate people from organizations? Also, unless its general open funding, I assume all the sponsors also contributed ideas and/or design?

[saulshanabrook]

Does everyone who makes a PR become a contributor? If so, I find that buries the signal in the noise when projects have done that. There should be some community agreement to make the front page of the project. I find the all contributors project page hard to figure out who is active and key to this project. When I look here, it clearly just a couple of key people.

Good point. I just added a pointer to Contributors page in the readme if you are looking for who is active now, instead of who has contributed in the past. Alternatively we could keep something like our "Team" page but I find it quickly get out of date. For example, Athan is one of the top committers and has recently been doing most of the development, but is not listed in the Team section. Max isn't either.

I don't love the money icon for sponsors - it looks crude and seems to not reflect that sponsorship of OSS is more of a relationship than a transaction. What about an icon like this (not OSI approved, but the idea is its a relationship). I guess the problem would then be diverging from https://allcontributors.org/docs/en/emoji-key.

Yeah that sounds good to me. It looks like can override the custom types to provide our own symbol.

Can we separate people from organizations? Also, unless its general open funding, I assume all the sponsors also contributed ideas and/or design?

We can add the other types to sponsors as we see fit. Also, if we wanted we could do it by person at the organization... For example we could add you as adding ideas/design instead of putting that on the organization. Depends on how we think about it. Do the organizations just contribute funding (for your salary and mine?) or are they contributing ideas?

Not sure if it lets you split it out. I can look into that.

[mlucool]

This goes back to some of the original points people brought up in various conversations on this: Do you recognize every contribution or just some? When is a contribution large enough? My hope is that whatever is chosen here becomes the template for other jupyter projects, so it's good to think about scale now.

In my personal opinion, I like versions that are more selective for the README. It should highlight key organizations and people that were important in the life of this project and, if possible, important now.

If we wanted to also recognize every contribution, it would be better to do it on a CHANGELOG (as suggested by Jason) because a single location would accumulate too many people over time otherwise (hopefully). This points away from automation and instead keeping it limited (and removing the line on how to add yourself). Fomik uses this style had has 330 people who have made commits, but only 10 are highlighted on the main page.

Also, if we wanted we could do it by person at the organization... For example we could add you as adding ideas/design instead of putting that on the organization. Depends on how we think about it. Do the organizations just contribute funding (for your salary and mine?) or are they contributing ideas?

People who interact with projects as part of their work often wear many hats. Very often the things they bring to the project are a combination of their own innovations and ideas from others inside the enterprise. Some developers get so involved in projects it becomes their side project too, unrelated to their day job or the organizations need. For the former, I think the sponsor organization is enough. The latter is exceptional and someone may flag themselves in that way.

[telamonian]

I don't think we've really answererd the fundamental question of "how do we record the history of our project?" On the other hand, the contributors list in the most recent version of this PR is definitely better than our existing Team section. So I think this should go in as-is.

I've rebased the PR, and will pull it once CI passes.

[telamonian]

If anyone wants to submit a followup PR fixing up their contrib emojis, I'd be glad to review it and get it in

[saulshanabrook]

Thank you Max!