| name | credits |
| description | Update the commit-authors table in doc/CREDITS.md from the latest git history. Run `just authors`, merge the new counts into the table, refresh notes for authors whose commit count grew significantly, and move them into the correct digit-section. Use for the periodic (e.g. year-end) CREDITS refresh. |
Updating the CREDITS.md commit-authors table
doc/CREDITS.md holds a table of everyone who has committed to hledger, with a
short note summarising each person's contributions. site/src/CREDITS.md is a
symlink to it, so only edit doc/CREDITS.md.
The task: bring the table in sync with current git history — update counts, add
new contributors with notes, refresh notes for people whose contribution grew,
and keep everyone in the right section.
Table structure
The table is authored in Markdown with embedded HTML, rendered by mdbook:
| Author | Notes |
|----------------------------|------------------------------|
| <h3><a name=five-digits href="#five-digits">5 digits</a></h3> |
| <!-- 13594 --> Simon Michael | founder, project leader, lead developer |
| <h3><a name=four-digits ...>4 digits</a></h3> |
| <h3><a name=three-digits ...>3 digits</a></h3> |
| <!-- 477 --> Stephen Morgan | performance, code cleanup, ... |
...
Key points:
- Authors are grouped into digit-sections by commit count:
5 digits
(10000+), 4 digits (1000+), 3 digits (100+), 2 digits (10+),
1 digit (1-9). Each section starts with an <h3> anchor row. A section can
be empty (just its header, e.g. 4 digits).
- The commit count lives in an HTML comment
<!-- N --> at the start of the
first column, so it is hidden in the rendered page but still visible/editable
in source. The visible cell is just the name (right-aligned by the <style>
block above the table).
- Within a section, rows are sorted by count descending.
- An inline
<style> block just before the table right-aligns the Author
column, left-aligns Notes, and removes link underlines. Leave it in place.
- Below the table is a
contrib.rocks avatar image.
Workflow
1. Get the current author counts
git shortlog -sn main
Also useful:
git shortlog -sn main | wc -l
git shortlog -sn main | awk '{s+=$1} END{print s}'
git log main --reverse --format=%as | head -1
2. Reconcile the latest author names the table
Names are canonicalised by .mailmap, but new contributors, renames,
and alias/case duplicates still need handling. Diff the shortlog names against
the table's names and investigate each difference:
git shortlog -sn main | sed -E 's/^ *[0-9]+\t//' | sort > /tmp/shortlog.txt
For any name that appears/disappears, check the underlying identity before
deciding it's a new person:
git log main --format='%an <%ae>' | grep -i NAME | sort -u
grep -i NAME .mailmap
Common cases:
- Case/alias duplicates (e.g.
ooker/Ooker, ob for a real name) — same
person, git counts them separately. Fix by adding a .mailmap entry, then
re-run the shortlog so counts merge, before updating the table.
- Misattributed commits (e.g.
root <root@localhost>) — usually a
maintainer's commit from a misconfigured machine. Map to the real person in
.mailmap (Real Name <email> <bad@host>), re-run shortlog, and drop the row.
- Genuinely new contributors — add a new row (see step 4).
.mailmap format is Proper Name <canonical-email> (canonicalise a name) or
Proper Name <canonical-email> <alias-email> (merge an alias). It's sorted
case-insensitively.
Ask the user about anything ambiguous — which of two spellings to display,
whether two identities are really one person, whether to include a junk row.
3. Update counts and re-section
For each existing author, update the <!-- N --> count. If a new count crosses
a digit boundary (e.g. 9 → 12, or 99 → 100+), move the row into the correct
digit-section and re-sort it within that section by descending count. Keep
the section header rows; a section may become empty or newly non-empty.
Update the stats line and Simon Michael's count at the top:
Stats as of YYYY-MM-DD: **NNNNN commits in NN years by NNN people**
4. Write notes for new authors
Every author should have a brief note. For a contributor with no note, read
their commit subjects and summarise in the existing style — lowercase-ish,
phrases separated by ;, naming the command/feature/area (e.g.
csv encoding rule; html export fix, tsv output format,
hledger-ui Windows support). One short clause is fine for a single commit.
git log main --author="NAME" --format='%s' | grep -v '^Merge ' | awk '!seen[$0]++'
Match the tone and brevity of the surrounding notes.
5. Refresh notes for authors whose count grew significantly
Identify authors whose count rose a lot since the last update (compare the old
table counts from git against the new shortlog; a threshold like +5, or a digit
boundary crossing, works well):
git show main:doc/CREDITS.md
For each significant grower, look at their recent commits and fold the new
work into their note (and move them up / into the higher section if warranted).
Filter out noise (dev/doc/cln/test/merges) to find the substantive work:
git log main --author="NAME" --since=LAST_UPDATE_DATE --format='%s' \
| grep -viE '^;?(dev|doc|cln|test|ref|Merge)' | sort -u
Keep the existing note's good content; append or integrate the new areas rather
than rewriting from scratch. Prefer concise phrasing over an exhaustive list.
6. Verify
- No author row left with an empty note.
- Every author is under the correct digit-section, sorted by count within it.
- Column alignment/padding is consistent with neighbouring rows (match the
existing whitespace; the note column is padded to a fixed width).
- Stats line, Simon's count, and people/commit totals all agree with the
shortlog.
git diff .mailmap doc/CREDITS.md reads cleanly.
Notes
- Do not hand-edit
site/src/CREDITS.md — it's a symlink to doc/CREDITS.md.
- Doing the bulk merge/re-padding with a small script (Python) is far more
reliable than editing ~200 rows by hand; verify alignment afterwards.
- When merging identities via
.mailmap, always re-run git shortlog -sn main
before touching the table so the counts already reflect the merge.
