[HN Gopher] Git log is not a changelog ___________________________________________________________________ Git log is not a changelog Author : agateau Score : 21 points Date : 2022-07-16 21:12 UTC (1 hours ago) (HTM) web link (agateau.com) (TXT) w3m dump (agateau.com) | mulle_nat wrote: | I use the git log to feed my changelog. I prefix the stuff that's | supposed to go in the release notes with a asterix and the | technical boring stuff is just a normal line. Then at release | time I have a script that pulls the asterix prefixed lines from | the change log into the RELEASENOTES.md. I wouldn't want to | bother with more. | kreeben wrote: | How do you know that your asterixed commit should go into the | release notes? What if... | | * fixed thing X so that user can do Y | | broke things so that another commit is needed: | | * fixed X again, so that user can finally do Y (for realz this | time) | | This would not make a great release note. | ehPReth wrote: | you just wouldn't put a * in front of the second one | sss111 wrote: | use https://www.conventionalcommits.org/en/v1.0.0/, it has | extensions that can autogenerate a nice looking changelog. | jasonpeacock wrote: | Yep, something like Git Cliff[1] is great for generating | release notes from your commit messages. | | And conventional commits are good thing to do regardless of | whether you use them for release notes or not. Commit messages | should be helpful and immediately obvious, too often its "fixed | bug" or "finally figured out foo!", which really tell you | nothing - might as well not have a message. | | [1] https://github.com/orhun/git-cliff | foxhop wrote: | no changelog until somebody complains? | _ph_ wrote: | Yes, a commit log isn't a changelog. However, a good commit log | can make writing your change log much easier. While this isn't an | automatic process, writing a changelog becomes a bit of filtering | of the commit messages as well as rephrasing them for the | intended audience. | cperciva wrote: | FreeBSD uses Relnotes: yes, or text for the | release notes | | in commit messages to note that the commit has significant user- | visible effects. | lhnz wrote: | I think commits should contain atomic-yet-meaningful changes and | the commit message should describe this as well as possible. | | It's worth rewriting the history to achieve this and squashing or | splitting commits until this is the case. You shouldn't do this | for the benefit of your users or a changelog, you should do this | in order that it is easier to bisect the history or for other | contributors to understand exactly the change a commit relates | to. There is nothing worse than commits which combine a working | bug fix with a half-written feature -- split them out! | | Obviously, it's possible to inadvertently create a misleading | history by re-arranging the order that work was done or getting | rid of failed attempts at a solution, but generally the false | reality is easier to understand and good understanding is key. ___________________________________________________________________ (page generated 2022-07-16 23:00 UTC)