I recently experienced firsthand the frustration of poorly documented changes. While maintaining a legacy application with limited handoff from the previous developer, I found myself leaning heavily on the git log to understand how parts of the application were intended to behave. It sucks to do version control archaeology and find that the commit message for a line of code you’re puzzling over is “WIP” or something equally useless. References to ticket numbers are helpful only if the maintainers know what issue tracking system you were using and still have access. Don't assume that will be the case. Remember that idioms change over time, so something obvious now might be obscure in 5 years.
Commit history may be one of the only communication channels between you and your application's future maintainers. Think of it as a captain’s log for the project. It should document what decisions were made and why. Anyone can tell from the diff that you tweaked the configuration / made the column nullable / removed CSRF checks for an action, but why were those changes needed? As the committer, you are uniquely qualified to answer that question for future readers. A few extra sentences to explain your intent and reasoning could save a maintainer wasted time or prevent them from introducing a defect. If you're working on a feature branch and all your commits are "WIP", take the time to do an interactive rebase and clean up your commit messages.
Some examples:
Commit message:
Change delayed_job config
More useful commit message:
Change delayed_job config.
- Disable retries since failed jobs will continue failing.
- Leave failed jobs around so we can inspect them
Commit message:
Use url_keys instead of ids in routes.
More useful commit message:
Use url_keys instead of ids in routes.
This will obfuscate urls and thereby prevent users from accessing resources that were not shared with them.
Commit message:
WIP
More useful commit message:
Change 'active' scope to exclude customers with no invoices within the past year.
This was done to help performance by reducing the number of invoices loaded by default.
You get the picture. Take a couple of extra minutes to describe the changes and why they were needed. Your maintainers will appreciate it someday!