This avoid merge hell on the CHANGELOG.md file.
Right, if you don't do something like this you can be in merge hell very quickly...
Sometimes, my Git commits can be kind of verbose (and I'll occasionally put in smartass comments).
I wouldn't dream of mining my Git logs for CHANGELOG entries.
Actually, I hand-run many things that a lot of developers automate.
Part of it is because I have control issues...
It felt kind of silly and I don't know if anyone actually looked at the changelogs, but it took 2 minutes out of my day and worked well.
Why? Every time I have asked this people say because you'll search the logs (which I have never done in my life) or because "it's good practice"
Sometimes it turned out to be a mistake in the original commit, or working around a limitation that no longer exists, other times it has saved me from re-introducing a bug that someone had spent effort fixing.
For isntance, when you use "git blame" and similar tools, the log messages are not involved. You might end up reading the log message of the commit that was responsible for a change, but you didn't search log messages to get there.
In a project with poor commit messages, they will be of little use; reading them won't produce much value, let a lone searching.
Anyway, that seems like the best possible interpretation of the user's comment, anyway.
The commit message explains (/should explain) why the commit was made. That is useful even if you arrive at the commit via git blame, bisect, etc.
If the person still works with you, you can just ask them about it.
If they don't or you don't want to bother them, the commit message tells you what the change was and often times why to give you a better context.
All the teams I've worked on included information like feature, bug, defect, and the associated ticket number in the branch name, so you have the information at hand to go look at the ticket directly and see what requirements were needed.
Usually people 'own' a file or part of the system so that wouldn't really be happening anyway
Because sometimes we can learn from history. If a mistake was made at some point it can be good to understand why. Of course you can adopt the mindset that you don't care what ended up causing a bug, but learning from mistakes is a good thing.
> see if someone modified a test I thought was covering the case
How do you see if someone modified the test then? I feel like we are maybe misunderstanding eachother because to me, and seemingly most other commenter here, this is such an obvious no-brainer that it seems something is lost in the communication.
A commit message helping me learn anything that I didn't get from a code comment sounds like a stretch. I'm doubting this
> How do you see if someone modified the test then? I feel like we are maybe misunderstanding eachother
Clearly. I was suggesting I might see commit messages if I'm using git blame to find out if a case was removed from a set of test or if it never existed in the first place. But I don't see how messages would help at all in anything I do. What I'm looking for is far too specific to be in a commit message and this whole thread about using commit messages to learn sounds nonsensical.
As an example, say log messages are strictly required to contain a bug database ticket number (even if they are not fixes: bug database tracks tasks too) then that is useful; you can quickly search the git log for a bug number to find all of its commits.
Maybe it depends on the project but I've found myself doing this so often that I won't stop, it's such a small task that has given me so much benefit. If it doesn't help anyone then nothing was lost.
Why does the code fence against a particular circumstance you didn't think should be possible? Why does it call out to something you think is unrelated? Those questions can be answered by a proper commit message.
JIRA: #1234
Adjusted the FOOBAR parameter from 42 to 73.
To know the "why", you have to read the ticket; you will not find anything in the git log.https://news.ycombinator.com/item?id=32104697
https://news.ycombinator.com/item?id=32086054
https://news.ycombinator.com/item?id=32085905
https://news.ycombinator.com/item?id=32085736
We eventually ban accounts that carry on like this on HN. I don't want to ban you, so if you'd please review https://news.ycombinator.com/newsguidelines.html and stick to the rules when posting here, we'd appreciate it.
For example (one that you linked to) a person said I was wrong and his comment wasn't flagged yet when I asked him to stop replying to my comments (many of my comments in the thread weren't on his comments) mine gets flagged https://news.ycombinator.com/item?id=32086054
If you see a post that ought to have been moderated but hasn't been, the likeliest explanation is that we didn't see it. (There are far too many posts here for us to read them all.) You can help by flagging it or emailing us at [email protected].
https://hn.algolia.com/?dateRange=all&page=0&prefix=true&sor...
You _could_ tag every line of code with
// JIRA-123 The PM wants this to be blue
but if you did it would become unreadable and wouldn't be kept up to date.- written by people who were not me
- written by people who have since left the company
- the original documentation has rotted away through wiki replacements, issue tracker replacements, or being lost via people turnover or system replacement.
The result in many cases is the code is the _only_ documentation of the system behaviour, so seeing what was introduced together is important context to understanding why it is the way it is. I probably run git blame more than git commit at this point and there's a real QoL difference between the good commit messages and the "changes for ticket12345" commit messages.
I can’t even imaging having a spec that fully answers anything like this; Microsoft tried for that level of detail but I found they couldn’t keep it up to date.
If a bug pops up, you'd want to know why some code exists and if the original premise of the code is as it should be or needs revision.
I think it's very rare that a developer receives all that information up front in a team. Eg. Old codebase, lost knowledge or people leaving.
The changelog, on the other hand, answers the question “why does the customer care about these changes?” It could be the same reason as why the commit exists, but the question is different. If the customer doesn’t care, maybe it doesn’t even need an entry. Maybe why they care is slightly different than the reason the commit(s) exist.
This is why I advocate for a hand-updated CHANGELOG.md. It’s a very small amount of writing that forces developers to consider how their PRs will impact customers that an auto-generator will never be able to do well.