How to Write Useful Commit Messages
a day ago
- Effective commit messages simplify code reviews, communicate changes to teams and users, aid future debugging, and provide data for development tools.
- Structure commit messages using the 'inverted pyramid' style, placing the most critical information first, and use headings for long messages.
- The commit title should describe the effect of the change ('what'), while the body must clearly explain the motivation ('why') and how it impacts users.
- Provide essential context by cross-referencing issues and bugs, summarizing external references, and justifying new dependencies.
- Document learnings, alternative solutions considered, testing instructions and limitations, and searchable artifacts like specific error messages.
- Highlight breaking changes, supplement UI changes with screenshots/videos, and place rants or stories at the very end of the message.
- Leave out information obvious from the code diff, ephemeral review discussions, and critical maintenance details that belong documented directly in the code.