- `brew contributions --user=issyl0` was taking forever because it went
through all maintainers first, because the conditionals were in the
wrong order.
- This was too quiet, far too quiet, for something that takes so long.
- Now verbose mode tells you what repos it's scanning for a user.
- With `brew contributions`, this will output a list of stats
(across the specified time period, or all time) for people in the
"maintainers" team on GitHub.
- Add a `--user` flag for getting stats for a specific user (either
username, name or email address).
- This assumes that their Git committer details are the same as their name is
set to on GitHub.
- Show an error message if trying to generate a CSV for the full maintainer
list, since I haven't worked out how to best show all of that info yet (or
even how best to show only the totals across everything for every user) in
that format.
- Using `git log` was brittle with name changes and email address changes for
contributors over the years unless we made a Git `mailmap` file which brings
with it its own updatedness overhead.
- Let's use the GitHub commits API (importantly _not_ the search API) so that
we can give it a username and it will return contributions associated with
every email address on that user's account:
https://docs.github.com/en/rest/commits/commits?apiVersion=2022-11-28#list-commits--parameters.
- This is quite significantly slower, but it's worth it for correctness
especially when we get to all maintainers' contributions (in a separate PR).
- The commits API does not (yet?) support trailers or commit "committer"s, just
authors.
- For annual "has this person contributed enough", we focus on the main
Homebrew repos: brew, core and cask. Let's make that easier than
`--repositories=brew,core,cask`.
```
$ brew contributions issyl0 --csv
The user issyl0 has made 1202 contributions in all time.
user,repo,commits,coauthorships,signoffs,total
issyl0,brew,332,13,0,345
issyl0,core,473,24,326,823
issyl0,cask,4,0,0,4
issyl0,aliases,0,0,0,0
issyl0,autoupdate,1,0,0,1
issyl0,bundle,14,2,0,16
issyl0,command-not-found,1,0,0,1
issyl0,test-bot,3,0,0,3
issyl0,services,9,0,0,9
issyl0,cask-drivers,0,0,0,0
issyl0,cask-fonts,0,0,0,0
issyl0,cask-versions,0,0,0,0
```
- This gives users of this command a `--csv` option to pass to... you guessed
it, generate a CSV that's `pbcopy`able elsewhere, for more granular
breakdowns of where a person contributed.
- Inspiration was taken from the mockup in
https://github.com/Homebrew/brew/issues/13642#issuecomment-1254535251
but without the extra dependency of the TerminalTable gem.
- Always print a condensed "total contributions" sentence.
Output:
```
$ brew contributions issyl0
The user issyl0 has made 1201 contributions in all time.
$ brew contributions issyl0 --csv
user,repo,commits,coauthorships,signoffs
issyl0,brew,331,13,0
issyl0,core,473,24,326
issyl0,cask,4,0,0
issyl0,aliases,0,0,0
issyl0,autoupdate,1,0,0
issyl0,bundle,14,2,0
issyl0,command-not-found,1,0,0
issyl0,test-bot,3,0,0
issyl0,services,9,0,0
issyl0,cask-drivers,0,0,0
issyl0,cask-fonts,0,0,0
issyl0,cask-versions,0,0,0
```
❯ brew contributions mikemcquaid
mikemcquaid directly authored 23766 commits, co-authored 241 commits, and signed-off 6730 commits across all Homebrew repos in all time. Total: 30737.
- This doesn't require "all" to be specified as part of the command,
it's the default, so usage is now just:
```
$ brew contributions "Issy Long"
$ brew contributions "Issy Long" --repositories=brew,core
$ brew contributions me@issyl0.co.uk --repositories=cask,bundle
```
- As we discussed in the PR review before, `comma_array` doesn't allow
two names, so we can't (yet) do `comma_array "--repositories",
"--repos"` like we can with `flag`. That's an enhancement for the future
if we want to make the flags here less verbose. But now that "all" is
the default, maybe less necessary.
- Also stop skipping a "versions" repo. Since
023261038192a4f55c95a4d2486873ec1c9a728a the
`Homebrew/homebrew-cask-versions` tap won't get mistaken for
`Homebrew/homebrew-versions` tap.
- This is easier than mapping GitHub usernames to email addresses, when
folks don't have email addresses always public on their GitHub
profiles. Also, the users of this command (PLC members, other
interested parties) don't have to remember folks' email addresses.
- It also gives better data for people who've changed their name over
the years, and who commit with multiple email addresses (personal and
work).
```
❯ brew contributions "Issy Long" all
Person Issy Long directly authored 687 commits and co-authored 33 commits across all Homebrew repos in all time.
❯ brew contributions "Rylan Polster" all
Person Rylan Polster directly authored 1747 commits and co-authored 133 commits across all Homebrew repos in all time.
❯ brew contributions me@issyl0.co.uk all
Person me@issyl0.co.uk directly authored 711 commits and co-authored 25 commits across all Homebrew repos in all time.
❯ brew contributions "Mike McQuaid" all
Person Mike McQuaid directly authored 26879 commits and co-authored 204 commits across all Homebrew repos in all time.
```
- This is apparently "more in-keeping with how we do required arguments
(never requiring flags)" across Homebrew.
- New usage: `brew contributions me@issyl0.co.uk all`, `brew
contributions me@issyl0.co.uk brew,core`
- I got these with hash syntax because I couldn't figure out Sorbet, but
there's `args.rbi` to add the CLI args methods to. Nice!
- In doing this I realised that `--repositories` is required again, we
no longer infer `--repositories=all` from no `--repositories` passed
as we did in a previous version of this.
- This way we can do the more intuitive:
```
$ brew contributions --repos=brew,core rslpolster@gmail.com
Person rslpolster@gmail.com directly authored 1580 commits and co-authored 125 commits to brew, core in all time.
```
- Before each AGM it's currently a manual process for a PLC member to
search commit logs and GitHub to figure out who contributed to
Homebrew, so who should remain a member.
- I noticed that [looking at commits for a
user](https://github.com/Homebrew/homebrew-core/commits?author=issyl0&since=2022-01-01&until=2023-01-01)
would not count `Co-Authored-By`, which happens a lot now there's an
autosquash action on PRs in `Homebrew/homebrew-core`, say if someone
fixed a formula's build or tests or whatever and then the PR got
auto-merged.
- Here's `brew contributions` that uses `git log` to be able to go back
through all time or a specific time period (`--from`, `--to`). It's up
to individual PLC discretion for "activity", but it does at least go
some way to automating the data retrieval.
- Example (I can use my username as `--email` because my username is in
all of the email addresses that I use for committing to Homebrew):
```
$ brew contributions --email=issyl0 --repos=brew,core
Person issyl0 directly authored 732 commits and co-authored 31 commits to brew, core in all time.
```
