[HN Gopher] The Subtle Art of the Changelog
       ___________________________________________________________________
        
       The Subtle Art of the Changelog
        
       Author : GarethX
       Score  : 31 points
       Date   : 2023-01-25 13:53 UTC (9 hours ago)
        
 (HTM) web link (www.commandbar.com)
 (TXT) w3m dump (www.commandbar.com)
        
       | anonymoose33282 wrote:
       | I'm one of the people who always glances at changelogs when
       | downloading an app for the first time, and I appreciate when
       | developers go beyond 'Bug fixes and minor improvements' to at
       | least list a couple concrete things that were added. I'm sure I'm
       | in the minority, but I like the extra effort.
        
         | GarethX wrote:
         | Yeah, in times of auto-downloading updates, I can see why many
         | don't, but I certainly appreciate it when they do.
        
       | dazzeloid wrote:
       | I feel like a lot of companies put effort into their changelog in
       | the early days when they're trying to cultivate their first users
       | and know every user personally. But then I see them inevitably
       | fall into the "bug fixes and performance improvements" laziness.
       | 
       | Would be a cool (but painful to do) analysis to look at whether
       | this happens and at what scale companies throw in the towel.
        
         | GarethX wrote:
         | That's what I respect about Citymapper in the linked article -
         | they're 11 years in and still putting in the effort to their
         | updates.
        
       | olddustytrail wrote:
       | When everything is in git and you have the log anyway, is there
       | really any use for a changelog?
        
         | misnome wrote:
         | Different audiences. A Changelog is read by the users of your
         | software, the commit message by the developers. It's rare that
         | a commit message is suitable for both.
        
         | pan69 wrote:
         | When you want to publish your changelog to your users you
         | probably want to have some standards around your commit
         | messages and when you do, from the commit history you can then
         | automate the creation of a changelog.
         | 
         | https://www.conventionalcommits.org/en/v1.0.0/
        
         | mikewarot wrote:
         | Git commit messages are written under time pressure, change
         | logs allow you to refactor the history and clarify things as
         | facts become known.
        
       | Macha wrote:
       | My personal ranking of changelog styles I've seen in the wild:
       | 
       | 1. Categorised list of human-written points, e.g. breaking
       | changes/features/bugfixes for developer facing software, features
       | with overview of how to use them for end user facing (see vs
       | code)
       | 
       | 2. Breaking changes, followed by git shortlog
       | 
       | 3. Developer picked highlights only
       | 
       | 4. Literally just the git shortlog
       | 
       | 5. A bunch of issue tracker links (especially if you later decomm
       | that issues tracker)
       | 
       | 6. Nothing
        
       | misnome wrote:
       | We used to... somewhat attempt manual changelogs. Every time it
       | came to a release the release manager would ask around for what
       | the key changes were, and we usually ended up with only a couple
       | of entries.
       | 
       | Now, we use https://github.com/twisted/towncrier . Every change
       | goes through pull requests, and _every_ PR _must_ have a
       | newsfragment file - and we enforce this with a test that fails if
       | it isn 't present (with convenience functions of rewriting the
       | number to match the PR if you name the news file XXX.{category}).
       | If it's not a user-facing change, then we just have a category
       | that is ignored.
       | 
       | On releases (or on individual PRS along the way), the release
       | manager generates the changelog, but also edits them into a
       | relatively coherent style (or rewrites developers news fragments
       | along the way).
       | 
       | Every change has a note written aimed at the user. Every entry in
       | the changelog has a link to the relevant PR or commit. We have
       | much better changelogs now.
        
       | teddyh wrote:
       | _The_ standard for ChangeLog files:
       | 
       | https://www.gnu.org/prep/standards/standards.html#Change-Log...
       | 
       | Of course, what everybody is now calling "Changelog" used to be
       | known as a "NEWS" file:
       | 
       | https://www.gnu.org/prep/standards/html_node/NEWS-File.html
        
       | nickcw wrote:
       | When I make rclone releases I usually spend an hour or two taking
       | the git log, removing irrelevant stuff and rewriting messages to
       | make them make sense from a users point of view.
       | 
       | I then take that and try to pick the top 3 or so items for use in
       | the summary.
       | 
       | I then rewrite the summary condensing into a tweet.
       | 
       | It's a lot of work!
        
       ___________________________________________________________________
       (page generated 2023-01-25 23:01 UTC)