Commit Messages: “Fixed Stuff” vs Conventional Commits (Prompts)

Run git log --oneline on the repository behind streakpad, an open-source music practice tracker with 1,240 stars and 87 contributors, and the first page is a museum of wasted history: “fixed stuff”, “oops”, “wip”, “more timer changes”, “revert of the thing from yesterday”. The app has a practice timer, a streak counter, and a sync layer, and after six months nobody can tell from the log which of the 418 merged pull requests touched the timer and which touched sync, or which release a regression arrived in. When contributor Ivy Chen tried to write release notes for version 2.4.0, she read 60 commit subjects and learned almost nothing.

The problem is not that contributors are careless. It is that the prompt they hand to their assistant asks for a description, so a description is what they get back. Below are the two prompts, run against the same staged diff for the same timer fix, plus the skeleton the project pinned in its contributing guide.

Why the Log Stops Being Useful

A commit subject is read in three places, and a vague one fails in all three. It appears in git log when someone is tracing a bug, in the pull request list when a maintainer is reviewing a batch, and in the changelog when a release is cut. “Fixed stuff” tells the reader nothing in any of those contexts, so they open the diff, which is exactly the work the message was supposed to save them.

Automation makes the cost sharper. streakpad generates its changelog from commit history and tags releases with semantic versioning, so the tooling needs to know whether a change is a feature, a fix, or an internal refactor. A log full of “wip” gives the tooling nothing to group, and the changelog comes out as an undifferentiated list. Once you rely on machines reading your history, the message format stops being a style preference and becomes an interface.

There is a quieter problem: a vague message hides whether the commit should exist at all. When you force yourself to name the type and the scope, a commit that changes the timer and the sync layer and the docs in one go becomes visibly wrong, and it gets split. The message discipline catches the history problem before the history is written. The same reasoning sits behind a written code comment style guide, but applies earlier, at the moment you save a change.

Two Prompts for the Same Staged Diff

Both prompts receive the same diff: a fix that stops the practice timer from losing seconds when the app is backgrounded on Android. The first asks for something friendly.

Look at my staged changes and write a commit message for them.
Keep it short and simple. Something like "fix timer bug" is fine,
just describe what I changed.

That prompt produces exactly what it asks for, which is the problem. Now the version in the contributing guide.

You are writing a commit message for the streakpad repository, which
follows Conventional Commits v1.0.0 and generates its changelog from
commit history.

Read the staged diff below and produce one commit subject and one body.

Format:
type(scope): imperative summary

Allowed types: feat, fix, refactor, perf, docs, test, chore, build
Allowed scopes: timer, streak, sync, settings, auth, ui, deps

Rules:
- Subject is 72 characters or fewer, imperative mood, no trailing period.
- Scope must be one of the allowed values; if the diff spans two scopes,
  say so and recommend a split instead of writing a subject.
- Body: wrap at 72 characters, explain the user-visible effect and the
  root cause, not the mechanics of the edit.
- Add "Refs: #NNN" if the diff or branch name contains an issue number.
- If the change is breaking, add an exclamation mark after the scope.
- Do not describe the diff line by line.

Staged diff: [paste diff]

The first prompt leaves the format, the vocabulary, and the decision about scope entirely to the model. The second supplies a closed type list, a scope list, a length limit, and an instruction to refuse when the diff is too broad.

What Each Prompt Writes Into the Log

The loose prompt returns lines that read like the existing history, which is how the history got that way:

  • fix timer bug
  • fixed background issue, also cleaned up some code
  • timer sync changes

None of them says whether the release tooling should treat the change as a patch, none names the affected module, and the second one hides a refactor inside a fix. The conventional prompt returns something a maintainer can act on:

  • fix(timer): keep elapsed seconds when app is backgrounded
  • test(timer): cover background resume on Android 14
  • and, when the diff is too broad: This change spans timer and sync. Split into fix(timer) and refactor(sync) before committing.

That third result is the one maintainers value most. A prompt that refuses a badly scoped commit is doing review work before the review starts. On the review side, a checklist of code review prompts covers the rest of the pull request, but a clean log is what makes the review fast in the first place.

Why the Conventional Prompt Scales

  • The type list is closed, so the output is machine-readable. Eight allowed types mean the changelog generator, the version bump, and the release notes all get a stable field to group on, instead of guessing from prose.
  • The scope list stops invented module names. Without it, contributors write fix(app), fix(timerlogic), and fix(background-timer) for the same area, and grouping breaks.
  • Imperative mood keeps the subject consistent. “Add pause on background” reads as a command to the codebase, which is the convention every automated parser and every senior reader expects.
  • The split instruction handles the real failure case. Most bad commits are not badly worded, they are too large. Asking the model to detect a two-scope diff turns the prompt into a guardrail.
  • The body rule separates cause from mechanics. “Root cause, not line-by-line” produces a body that helps whoever bisects the bug in eight months, which is the only reader who matters long term.
  • It is uniform across 87 contributors. The same prompt in the contributing guide means a first-time contributor and a maintainer of three years write history in the same shape.

You can see the payoff the moment you run the log through a changelog or docs generator: once subjects carry a type and a scope, release notes and project history can be derived instead of hand-written, which is the same discipline behind an AI-assisted README workflow.

A Drop-In Skeleton for Your Repository

You are writing a commit message for the {{repo name}} repository,
which follows Conventional Commits v1.0.0.

Read the staged diff below and produce one commit subject and one body.

Format:
type(scope): imperative summary

Allowed types: {{your type list}}
Allowed scopes: {{your scope list}}

Rules:
- Subject is 72 characters or fewer, imperative, no trailing period.
- Scope must come from the allowed list. If the diff spans two scopes,
  do not write a subject; recommend a split instead.
- Body wraps at 72 characters and explains the user-visible effect and
  the root cause, not the mechanics.
- Add "Refs: #NNN" when an issue number appears in the branch or diff.
- Breaking change: add an exclamation mark after the scope.
- Do not describe the diff line by line.

Staged diff: {{paste diff}}

Two parts of this are worth customizing per repository. The scope list should mirror your actual module structure, because a scope that does not exist is worse than no scope. The split rule should match your team’s merge policy: if you squash on merge, say so, and the prompt will stop recommending splits that your workflow cannot accept.

Checks Before You Push

  1. Does the subject survive being read alone in git log? If you need the diff to understand it, the subject is too vague, and the fix is usually to name the module and the effect.
  2. Is the type honest? A fix that also changes behavior in a new way is a feature, and mislabeling it corrupts the version bump the release tool computes.
  3. Would this commit be better as two? If the model recommends a split, that is a signal about the diff, not an inconvenience. Split it.
  4. Does the body explain why, not what? The diff already shows what changed. The body earns its place by recording the cause, the constraint, or the alternative you rejected.

Do this for a month and the log becomes the project’s second documentation surface. A new contributor can trace how the timer behaves without asking anyone, which is the difference between a repository that scales past a hundred contributors and one that stalls.

Sources & Notes

Prompt patterns here reflect common practice with GPT-4-class assistants in 2025. streakpad, Ivy Chen, and the commit examples are illustrative; no real project or contributor is described. Conventional Commits is a widely used public specification, and the type and scope lists shown are examples you should replace with your own. Clean commit history helps changelog tooling and bisection, but it does not replace review, tests, or a release process.

声明:1.本站所有文章,如无特殊说明或标注,均为本站原创发布。本网站中【文本生成/文生图】使用了DeeSseek人工智能生成内容技术, 算法来源说明:本网站未自行开发、训练或部署深度合成算法,所使用的人工智能算法来自:DeepSeek、Chatgpt、Google Gemini。 2.为了网站加载速度优化,本站预览图片进行压缩处理,所以有些不是太清晰,并不影响AI提示词生图、AI设计等内容。3.任何个人或组织,在未征得本站同意时,禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益,可联系我们进行处理。--GUUNN.COM