Acknowledge maintainers and major contributors in the readme

rarkins commented 3 years ago

This is an open source project and I'd like to acknowledge and thank the contributors in the readme. This includes my fellow maintainers (@viceice @JamieMagee) as well as active and repeat contributors such as @HonkingGoose @secustor @ikesyo @zharinov @fgreinacher. We can also have a section to thank those who made significant contributions in the past but have now decreased their involvement for whatever reason so we can avoid any awkward feelings of "dumping" someone from the list who is not contributing enough. Some may even move themselves between sections ;)

Thoughts?

viceice commented 3 years ago

Sounds good, should be on bottom. can be pretty long list. Should they show with avatar or a simple list? 🤔

HonkingGoose commented 3 years ago

This is an open source project and I'd like to acknowledge and thank the contributors in the readme.

There's a bot that you could use to automate this work, it's called all-contributors:

Link to homepage: https://allcontributors.org/
Link to source code: https://github.com/all-contributors/all-contributors

You can give commands like:

@all-contributors please add @HonkingGoose for ...

You can see how such a PR looks over here:

https://github.com/testing-library/eslint-plugin-testing-library/pull/436

If you don't want to add this bot (needs write rights to the repository!), you can install the CLI tool, and create update PRs manually.

viceice commented 3 years ago

I like that bot. 🙃

viceice commented 3 years ago

I think we should use a CONTRIBUTORS files, as the list can be huge. https://allcontributors.org/docs/en/bot/configuration

rarkins commented 3 years ago

So topics are:

Move contributors out of package.json and into CONTRIBUTORS?
Use bot to automate adding people
Having a manually curated section of our README for those who have especially contributed? (this issue)

BTW my purpose was to explicitly highlight/thank those who have contributed the most.

HonkingGoose commented 3 years ago

BTW my purpose was to explicitly highlight/thank those who have contributed the most.

If that's all you want/need to do, you can do that by hand, and update the section when needed.

I've ran git shortlog --numbered --summary on the current main branch to see who have a lot of commits on the main branch:

  5433  Rhys Arkins
  1067  Renovate Bot
   914  renovate[bot]
   552  Michael Kriese
   229  Sergio Zharinov
   199  HonkingGoose
   136  Sergei Zharinov
    98  Jamie Magee
    49  Ayoub Kaanich
    34  Sebastian Poxhofer
    32  Florian Greinacher
    23  Sourav Das
    21  IKEDA Sho
    20  singapore
    16  JYC
    16  Tobias Bieniek
    14  Hutson Betts
    14  Nikita Chashchinskii
    14  Rishabh Jain
    12  Joshua Gleitze
    12  mohd hassaan
    12  ylemkimon
    11  Adrien Lemaire
    11  Daniel Tschinder
    11  Maximilian Gaß
    11  Mike Bryant
    10  Dragomir Țurcanu
    10  Steven Hargrove
    SNIP I've truncated the list to not show contributors with less than 10 commits, though we have a lot of those!

Seems we need to thank the creator first, then our robot friends/overlords, and then the rest of the maintainers/contributors. 😄 🤪

fgreinacher commented 3 years ago

Thanks for thinking about this! I like the idea of all-contributors a lot because it values each and every contribution in the same way. I personally do not expect to be more visible than other, less active, contributors.

HonkingGoose commented 3 years ago

So topics are:
* Move contributors out of `package.json` and into `CONTRIBUTORS`?

* Use bot to automate adding people

* Having a manually curated section of our README for those who have especially contributed? (this issue)
BTW my purpose was to explicitly highlight/thank those who have contributed the most.

Use bot to automate adding people

I've tested the all-contributors CLI / bot myself, here are my findings.

The all-contributors CLI tool / bot cannot add any old contributions to the readme.md file. This means that somebody would need to add all 450 contributors manually. That would be a lot of work.

Manually seed list with valuable contributors/maintainers

If we only care about people who have contributed the most or most meaningfully, a manual migration is feasible.

I'm willing to make a PR that adds all people with more than 10 commits to the list using the CLI tool myself. 😉 That PR will also include anybody already listed in the package.json in the contributors array.

After that we use the CLI tool to add new contributors, or tell contributors to add themselves. 😉

rarkins commented 3 years ago

@HonkingGoose did you have any ideas about which file to put it in? I think I'd prefer to avoid bloating our package.json further and maybe even trim it, e.g. if we replace it with a dedicated "all contributors" file or perhaps part of the README?

HonkingGoose commented 3 years ago

If you want the Renovate project to use the All Contributors CLI:

You can configure all-contributors by updating the .all-contributorsrc JSON file. The data used to generate the contributors list will be stored in there, and you can configure how you want all-contributors-cli to generate the list.

https://allcontributors.org/docs/en/cli/configuration

If you want to use the bot, the JSON file is also called .all-contributorsrc.json:

You can configure the all-contributors bot behaviour by updating the .all-contributorsrc JSON file. The data used to generate the contributors list will be stored in there, and you can configure how you want @all-contributors to generate the list.

https://allcontributors.org/docs/en/bot/configuration

So if you want to use the CLI or bot here's what I would do:

Remove all contributors from package.json
Add all contributors from package.json into the .all-contributorsrc.json file by hand with the CLI tool.
The CLI will add a new section at the very bottom of the README which will have a table of all contributors with their GitHub icons on them.
Merge changes from main into migration branch.
Run git shortlog --numbered --summary and only migrate people with 10 or more commits (keeps scope of manual work reasonable).
Open PR to get reviewed and double checked. 😄
Adjust table layout, GitHub avatar size until we're happy with the display.
From then on out we can use the CLI or Bot to add each contributor, or each contributor with a valuable contribution, or repeated contributions.

rarkins commented 3 years ago

Sounds great! I like using the bot

HonkingGoose commented 3 years ago

@rarkins Do you want a migration PR from me?

viceice commented 3 years ago

sure, if you able / have time to do it 🙃

HonkingGoose commented 3 years ago

I'll go try to migrate us then. 😄

HonkingGoose commented 3 years ago

Items to do before this issue can be closed:

[ ] Configure CLI version of all-contributors
[ ] Try out all-contributors CLI version on try-out repository
[ ] Create configuration PR for production repository
[ ] Migrate people by hand according to the list I made with a new PR
[ ] Add documentation on how people can use the bot to add their contributions with a new PR
[ ] Add checklist item to PR template: "I have added my contribution with the all-contributors bot" or something similar with a new PR
[ ] Optional: create pinned issue explaining the changes, and telling people to add themselves if they want

HonkingGoose commented 2 years ago

Options researched

I researched the following options to add contributors in a somewhat automatic way:

Option 1.1: Use all-contributors bot
Option 1.2: Use all-contributors CLI, add good documentation on how a contributor can add themselves, call to action in pinned issue for prior contributors to add themselves.
Option 2: Add link to https://github.com/renovatebot/renovate/graphs/contributors in the README to show 100 most frequent committers, documentation https://docs.github.com/en/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors
Option 3: Cobble something together ourselves based on GitHub REST API "list repository contributors" to display the first 500 commits, rest anonymously. https://docs.github.com/en/rest/reference/repos#list-repository-contributors
Option 4: Do nothing, and wait for the ecosystem to improve, so either all-contributors becomes better and can import all contributors automatically, or GitHub adds a good way to display all contributors, not just a subset.

Rejected options:

Option 1.1 was rejected due to the noise of the bot making a new PR to add somebody to the all-contributors files.
Option 1.2 was rejected due to it being too complicated to use for newcomers, and no automated way to migrate old contributions.
Option 2: was rejected as it doesn't show everybody that ever contributed.
Option 3: was rejected as being too much work/hassle, and even then it only shows 500 contributors, so we will run out of named contributors very soon.

Chosen option (for now):

Which leaves us with option 4: Do nothing and wait for the ecosystem/tooling to improve.

Status of issue:

I'm going to consider this status:blocked for now, as I don't have any easy way forward, and we're basically stuck waiting for tooling to improve.

fgreinacher commented 2 years ago

Thanks for the deep research @HonkingGoose 👍

I’m wondering how hard it would be to write a tiny GH action that adds the contributor to the PR branch 🤔

HonkingGoose commented 2 years ago

I’m wondering how hard it would be to write a tiny GH action that adds the contributor to the PR branch 🤔

@fgreinacher You mean like a action that does something like this?

git clone pr-branch
yarn install
yarn all-contributors add username for emoji-key
git commit -m "chore: add username for emoji-key
git push pr-branch

You need a way to know what kind of contribution you want somebody to be added for. But you could get that from the PR or commit message:

if (commit-message === starts.with(fix: ) then yarn all-contributors add <username> for code
if (commit-message === starts.with(feat: ) then yarn all-contributors add <username> for code
if (commit-message === starts.with(refactor: ) then yarn all-contributors add <username> for code
if (commit-message === starts.with(docs: ) then yarn all-contributors add <username> for doc
if (commit-message === starts.with(tests: ) then yarn all-contributors add <username> for test
ELSE: if nothing matches, abort the run.

We'd also need to account for the case where people are already on the list, like if it tries to add me again for a doc contribution... 😄

But then you're basically duplicating part of the code for the all-contributors bot. There's one benefit though: we don't pollute our changelogs/repository with endless commits like: add @HonkingGoose for doc.

Note that this setup would only automate for things like code, docs, test, refactorings that happen via commits to the main branch. Things like design, research, PR reviews, tutorials, user testing, bug reporting and content aren't usually done via a commit. So we'd still need to add these people by hand.

HonkingGoose commented 2 years ago

Also, I'm not sure any action that originates from renovate org is allowed to write changes to a fork branch....

Also, I'm not sure that we can use starts.with(fix: ) as you can also have commit message/PR titles like: fix(git): resolve Git problem which will not be captured correctly...

rarkins commented 2 years ago

It would need to run as a maintainer PAT, which is a security risk

HonkingGoose commented 2 years ago

Oh okay, so pushing changes to a fork is right out... 😄

fgreinacher commented 2 years ago

Valid arguments, probably it's really not worth the effort here 😀 I guess the repository pulse has most information one might need. Seeing how the whole Insights site has evolved over the years I guess it'll become even better and maybe fulfill some of the needs here "for free".

HonkingGoose commented 2 years ago

User-created script to add old contributors (no license!)

Option 1.2 was rejected due to it being too complicated to use for newcomers, and no automated way to migrate old contributions.

There now is an automated way to migrate old contributions, see: https://github.com/all-contributors/all-contributors/issues/539#issuecomment-1036979017 for the discussion + link to a Python script. There's no license attached to the script, so I don't think we can use it under our own license.

It will still be hard for newcomers to add themselves even after we do the automatic insertion. So that part is still a blocker.

New idea: use script yearly to add all contributors

We could go for a totally new approach, where we only update the list of all contributors once a year. This means that we don't have any noise, don't need to tell our contributors to do something complicated to add themselves, and we credit any new contributions in the last year.

Let me know what you think! 😄

rarkins commented 2 years ago

Sure, sounds good. It will be manual and subjective but that's probably OK. I'd likely just go through the list of feat: authors and pick most of them, plus anyone else who's made repeated non-feature contributions such as yourself or @astellingwerf

HonkingGoose commented 2 years ago

Option 1: automatic script by somebody else

There now is an automated way to migrate old contributions, see: all-contributors/all-contributors#539 (comment) for the discussion + link to a Python script. There's no license attached to the script, so I don't think we can use it under our own license.

I worry that if I try to integrate the custom code to list the contributors in our README.md that I'll get stuck and need help from others. So if we want to go this route, I'll need somebody else to get it working. 😄

Option 2: go full manual

I think I'd rather edit the readme.md file manually once a year, and stay away from more custom scripts.

I'd likely just go through the list of feat: authors and pick most of them, plus anyone else who's made repeated non-feature contributions such as yourself or @astellingwerf

Decision on direction by @rarkins

Which of these options do you like best @rarkins?

rarkins commented 2 years ago

I think I'd like to go with full manual mode. It would be good to note whenever there's someone actively maintaining certain modules or logic (e.g. @secustor is reliably available for Terraform topics), plus notable feature contributions in the past.

HonkingGoose commented 2 years ago

Do we want to overload our readme with a "thanks" section though?

If we're going full manual anyway, why not make it really cool and publish our thanks in the docs? We now have a About Us page that I could expand, or I can create a new file called thanks.md and put it somewhere suitable and publish that to the docs.

rarkins commented 2 years ago

True, docs would be great

HonkingGoose commented 2 years ago

Okay so we'll go full manual, and publish a thank word in our docs.

Should I update our about-us.md file in the docs repo, or do you want me to create a new file? If you want a new file, then please tell me where it should go. 😉

Can you review this todo list, and tell me if I'm good to go, or if I'm missing things?

[ ] Create new list of contributors with git shortlog --numbered --summary
[ ] Create new text with sections for:
- [ ] Notable feature contributions in the past, search for feat: commits
- [ ] Include frequent non-feature contributors like me or @astellingwerf
- [ ] Note who's actively maintaining modules/logic, like @secustor for Terraform topics
[ ] If needed: update nav list in mkdocs.yml config file on docs repo

HonkingGoose commented 2 years ago

@rarkins can you check the todo list I've posted just above this comment, and tell me if I'm good to start working on this?

rarkins commented 2 years ago

I think we can reuse about-us.md.

Here's what I'm thinking:

We can list @viceice , @JamieMagee and myself as maintainers, no need for further details.

There's maybe around 5 people who have helped maintain certain features specifically, and that deserves a special thanks next.

@HonkingGoose you are obviously the master of the docs, but I'd also propose you think of a term for yourself in addition such as "Community manager".

@zharinov has focused on parsing, Gradle, Maven, and he can remind me of other features.

@secustor Terraform, I think a couple of others.

@fgreinacher I recall some NuGet stuff in particular, any others areas you are happy to note as available for review/assistance?

@Turbo87 has helped in multiple areas, especially Cargo.

@ikesyo has been regularly helpful, as is @astellingwerf. I'm not sure what they'd list as their specialities.

Then finally there should be a section to pay thanks to those who've made valuable contributions in the past, even if one-offs. Some features made a lot of people happy and efficient! I would include for example the work of @danports here, unless he's happy to list himself as a "regular" contributor/advisor on any topics like Flux.

I think let's get it started, even if we accidentally/embarrassingly leave out anyone to begin with, we will fix it later.

HonkingGoose commented 2 years ago

Sounds good to me! I'll start working on this. 😉

fgreinacher commented 2 years ago

Thanks for thinking of me! Feel free to mention me for NuGet, sure.

danports commented 2 years ago

No need for acknowledgement here, but if it floats your boat to add me to a list somewhere, go for it. I haven't really been active since the Flux manager (and all of the others!) has been working well for me, but if there is an issue/PR that is Flux-related, feel free to tag me. Subscribing to all issues/PRs for the repo is kind of noisy (maybe a CODEOWNERS file could help?).

HonkingGoose commented 2 years ago

Subscribing to all issues/PRs for the repo is kind of noisy (maybe a CODEOWNERS file could help?).

I don't subscribe to all issues/PRs/comments as well, as that floods me with too many messages. 😄

The CODEOWNERS file only pings people with at least write level access to the renovatebot/renovate repository. GitHub warns about this when you go to our CODEOWNERS file:

Unknown owner on line 1: make sure @HonkingGoose exists and has write access to the repository

renovate-release commented 2 years ago

:tada: This issue has been resolved in version 32.66.5 :tada:

The release is available on:

GitHub release
32.66.5

Your semantic-release bot :package::rocket:

renovatebot / renovate