C.W.K.
Stream
Lesson 04 of 05 · published

git commit: Messages as Future Navigation

~20 min · commit, messages

Level 0Untracked Rookie
0 XP0/47 lessons0/14 achievements
0/100 XP to next level100 XP to go0% complete

Commit messages are navigation for future you

Six months from now, at 2 a.m., something will be broken. You will run git log -p -- offending-file and read the messages on every commit that touched it. Whether you find the cause in five minutes or two hours depends almost entirely on the messages your past self left. "fix stuff," "wip," "asdf," "save" — these are not commit messages, they are abandonment.

The conventional shape works because it is optimized for scanning history. Subject line: imperative mood ("Add", "Fix", "Remove" — as if you are giving Git a command), 50 characters or less, no trailing period. Blank line. Body: explain what and especially why, not how (the diff already shows how). Wrap at 72 characters so it reads in git log without scrolling. Footer: issue references ("Closes #142"), co-authors, breaking-change markers.

Two upgrades for team work. Conventional Commits add a type prefix (feat:, fix:, docs:, refactor:, test:, chore:) which lets release-tooling generate a changelog automatically. Semantic body with sections like Why, What changed, Risk, How to verify turns commits into reviewable evidence and replaces the bulk of "what is this?" Slack DMs.

The practical workflow: stage with git add -p, run git commit (no -m) to open your editor, write a real message in three minutes, save. -m is fine for trivial commits ("Fix typo in README") but actively harmful for substantive ones because it pushes you toward one-liners. Make writing a real message a habit before push. Future-you reads more commit messages than future-anyone-else.

Code

A real commit message·text
Add OAuth2 GitHub login to /auth/callback

Users previously created username+password accounts, which fragmented
identity across this app and their GitHub presence. The OAuth2 flow
unifies sign-in with the same provider where most users already live.

- /auth/github callback handles the code exchange
- Tokens stored encrypted with the AEAD column type
- Logout clears both session and provider tokens
- Profile page now shows the user's GitHub avatar

Risk: token storage migration runs on first deploy; rollback path is
to flip OAUTH_ENABLED=false. Rotation key is in 1Password "oauth-prod".

Closes #142
Refs RFC-2026-04-auth
Conventional Commits prefixes·text
feat(auth): add OAuth2 GitHub login
fix(api): handle empty array in /search response
docs(readme): document OAUTH_ENABLED flag
refactor(store): replace ad-hoc cache with TTL map
test(api): add property tests for /search edge cases
chore(deps): bump fastapi to 0.115.0
perf(query): index conversations.created_at
style: re-run prettier across frontend
ci: cache pip in GitHub Actions
revert: "feat(auth): add OAuth2 GitHub login"

# Breaking change marker:
feat(api)!: drop /v1/legacy-search endpoint

External links

Exercise

Find one of your worst recent commit messages ("fix", "wip", "updates", etc.) using git log --oneline | grep -iE '^[a-f0-9]+ (fix|wip|asdf|update)$'. For one such commit, draft what the message should have been: imperative subject, blank line, why-and-what body, optional footer. You do not need to rewrite history yet — just write the better message in a scratch file and compare.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.