Commit Messages

Clear, consistent commit messages make it easier for teammates (and your future self) to understand why a change was made.
This page explains how to write strong commit messages and provides examples of both good and bad patterns.

---

📚 Additional Reading

These guides explain the philosophy behind good commit messages:

• The Odin Project — Commit Messages
  https://www.theodinproject.com/lessons/foundations-commit-messages
• freeCodeCamp — How to Write Better Git Commit Messages
  https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/

If you're short on time, read the guidelines below.

---

🧠 Commit Message Guidelines

(Summarized from freeCodeCamp and industry best practices)

1. Capitalization and Punctuation

• Capitalize the first word.
• Do not end the subject line with punctuation.
• If using Conventional Commits, the type (feat, fix, refactor, etc.) remains lowercase.

Example:
Add fix for dark mode toggle state

---

2. Use the Imperative Mood

Write your commits like instructions or actions:

• “Add user authentication”
• “Fix navbar layout”
• “Update API route”

Avoid:

• “Added…”
• “Fixes…”
• “Updated…”

---

3. Specify the Type of Commit

Be clear about what kind of change you made.
Typical types:

• Bugfix
• Update
• Refactor
• Bump
• Add
• Remove
• Polish

Consistent wording helps maintainers read project history quickly.

---

4. Keep the Subject Line Short

• First line ideally ≤ 50 characters
• Body text should wrap at 72 characters

Short, clear, direct.

---

5. Write Meaningful Content

Avoid filler phrases like:

• “kind of”
• “maybe”
• “I think”
• “sort of”

Write what was done and why it matters.
Be specific, like a journalist.

---

✅ Examples of Good Commit Messages

• 5ba3db6 Bugfix failing CompositePropertySourceTests
• 84564a0 Refactor @PropertySource early parsing logic
• e142fd1 Add tests for ImportSelector meta-data
• 887815f Update docbook dependency and generate epub
• ac8326d Polish mockito usage

These are:

• Clear
• Specific
• Short
• Easy to scan in history

---

❌ Examples of Commit Messages That Need Work

• e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.

Problem: too long, too detailed for a single commit.

---

• 2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)

Problem: mixes multiple unrelated actions; uses past tense.

---

• 147709f Tweaks to package-info.java files

• 22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils

• 7f96f57 polishing

Problem: too vague — lacks explanation of what changed and why.

---

💡 Best Practices

• Write commits that represent one change.
• Commit frequently to show progress.
• Write commit messages that would still make sense six months from now.
• Think of the subject line as a small summary, and the body as optional context.

---

🔗 Next Step

➡️ Proceed to: Resolving Merge Conflicts