7 ms·

Keep a Changelog

275 points by privong 8y ago

okket 8y ago
Previous discussions: https://news.ycombinator.com/item?id=12370119 https://news.ycombinator.com/item?id=12370119 (45 comments, 3 years ago) https://news.ycombinator.com/item?id=9054627 https://news.ycombinator.com/item?id=9054627 (43 comments, 4 years ago) See also issues/pull requests in the repo: https://github.com/olivierlacan/keep-a-changelog https://github.com/olivierlacan/keep-a-changelog
simongr3dal 8y ago
Here's hoping this becomes mainstream again. The usual "Make sure to grab the latest update to get the greatest experience. We bring you performance improvements and bug fixes every 14 days" or some annoying joke about dusting code off, taking the trash out and fixing the space-time continuum is getting pretty tired.
- craftyguy 8y ago
  The most infuriating changelog lines are the ones that just say 'bug fixes' or 'enhancements' (or 'improvements'). Too many change logs have these lines.
  - Reedx 8y ago
    True, that doesn't really give much more info than "updated" does.
  - ygra 8y ago
    It's a bit annoying to document every single bugfix in a changelog too, though. At least I don't want to read dozens of lines like - Fixed flickering lower-right pixel when hovering over close button with a stylus on devices with more than 300 % UI scaling applied. - Fixed alignment issue in About dialog. - Improved help text for Gizmo frobbing feature. To me a changelog should prominently document changes in function and behaviour. I don't particularly care if an exception message got a typo fixed, but I do care about a new feature, if a login problem for a subset of users has been resolved or a crash under weird circumstances has been fixed.
    - craftyguy 8y ago
      > At least I don't want to read dozens of lines like I must be a crazy user, because I generally like reading through changelogs to see if an update is worth applying because it addresses a specific issue I am having, implements a new interesting feature I want to try, or fixes critical flaws. Luckily, though, public bug trackers are generally a good way to find out at least the 'is my bug fixed' part without the changelog (your issue is closed as 'fixed in X.Y')
    - stared 8y ago
      Yes, it is possible to mention such. It is not important for most users, but super important to ones affected by a given bug. Vide: http://us.battle.net/sc2/en/game/patch-notes/3-9-0 http://us.battle.net/sc2/en/game/patch-notes/3-9-0
  - bmalehorn 8y ago
    I have written exactly that kind of changelog. Let me explain why. I write the changelog for a product. In fact I write two changelogs - one for engineers and one for customers. Engineers: - [New Feature] Added ability to ___ - Improved logging on ___ - Fixed a memory leak on ___ Users: - [New Feature] Added ability to ___ Not every change can be explained in one sentence to users. Internal logging? Memory leaks? You're speaking a foreign language. Those entries must be thrown out when making the changelog for users. Eventually, there comes a release when you have thrown everything out. What do you write? "Bug fixes & enhancements".
    - _asummers 8y ago
      You could say something like "fixed stability in account management" or "fixed crash issues across application, improving stability across board". I sympathize with not wanting to go into more detail than would be generally understood by the audience, but there's a large chasm between "bug fixes" and that. If I was experiencing those bugs, I can now expect them to be fixed and I'm now in a better spot if I see them again to say "hey you didn't QUITE fix that in release X". If I see "bug fixes", I can't guess what happened in that release.
    - engerland 8y ago
      We already have our bug tracker for the engineers so why do twice the work? Most engineers don't care once the product is 'out' they only care what they're working on. So we create our change log (they are part of our 'release notes' actually) with only the user in mind but we reference the bug tracker number next to it. This is what we check in to the 'source' for the release notes. Then when we post to the 'outside world' we just remove those tracker numbers (takes a few seconds). That way the engineer can see the 'easy to understand conceptually' bug fix/enhancement and if they want to know more then they can see the Tracker reference and go and look up the 'real meat - with all the discussion and threads etc. For those bug fixes that we 'don't' document we have our source code software.
    - jaxn 8y ago
      We have 4 sections to every changlog release: New, Improved, Fixed, and Internal We maintain a CURRENT_CHANGES.md with those sections. When we do a release, we move the contents of CURRENT_CHANGES to a new entry in RELEASE_NOTES.md. One of these days, I will get around to writing something that displays RELEASE_NOTES in the app, without the Internal section
olivierlacan 8y ago
Since, as okket mentioned, Keep a Changelog has been featured on HN before let me give you... a changelog of what's happened in the project since the last time: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md#100---2017-06-20 https://github.com/olivierlacan/keep-a-changelog/blob/master... Version 1.0 was released introducing: a much cleaner website presenting the guidelines in a more digestible way; 13 new translations; a semi-decent versioning system to help synchronize translations; and a lot of clarifications and updates based on feedback and conversations that occur regularly within the project issues: https://github.com/olivierlacan/keep-a-changelog/issues https://github.com/olivierlacan/keep-a-changelog/issues. I know trying to get ahead of the torrent of critical comments is pointless but let me summarize: yes, I know you think changelogs have been defined before. But you know just as much as I do that most changelogs (or whatever you decide to call them in protest) are terrible and not as helpful to software end-users as they should be. There's been a lot of progress in the past 3 years alone in that regard. It's nearly unthinkable for an open source project to not include a decent changelog for each release. That's good. There are still a lot of smaller, less known, or older projects that could be improved with some basic changelog hygiene. If you're interesting in helping, please do, and if keepchangelog.com can help I'll be glad.
anonytrary 8y ago
Wouldn't proper use of `git rebase --interactive` make changelogs unnecessary?
- okket 8y ago
  No. The commit history is for the developer perspective, the changelog is for the user perspective. As a user you don't want and need all the details what changed between two releases. As a developer you absolutely need to be able to look this information up.
  - opk 8y ago
    I've always thought of the term changelog as being the full list of every single change for the purposes of developers. Back before we had git and used CVS or patches it was necessary to track all changes and this was often in a file named ChangeLog. User relevant changes go in release notes or (a NEWS file if you follow GNU conventions).
    - okket 8y ago
      Changelog is a bit ambiguous, indeed. Release notes would be a more fitting name, but also not ideal IMHO. If you want to know what was changed and when, you need the commit history anyway. Also for bisecting. I'd argue these days changelog and release notes are more interchangeable than changelog and commit history. The 'NEWS' GNU-ism never really caught on, maybe because news does not imply log/history.
- slaymaker1907 8y ago
  Not everyone who might be interested in your changelog will be a developer. Even developers don't want to go trawling through commit history to know changes at a high level.
  - anonytrary 8y ago
    Okay, fine -- but why couldn't you just derive a changelog from version-change commits which are meant for summarizing high-level changes in the version being committed? That way, you don't keep multiple sources of truth for version change information, while still benefiting from keeping a concise changelog without unnecessary commits in it.
todipa 8y ago
## [0.0.5] - 2018-08-28 - [Deprecated] Other system removed all access to GF; APIs not working anymore - [Added] Depression - [Added] Job at fast food retail ## [0.0.4] - 2016-03-13 - [Security] Found security vulnerabilities in GF; she always has a "headache" - [Removed] Job from daily life - fired ## [0.0.3] - 2013-02-12 - [Removed] Man and Lady - [Changed] Lady to Girlfriend - [Changed] Jobs to a higher paying one ## [0.0.2] - 2012-02-29 - [Removed] significant assets from bank account. - [Added] Purchased fast car. - [Deprecated] man and one lady from "hot" list ## [0.0.1] - 2010-11-04 - [Added] two ladies and a man from "hot" contact list - [Added] A job post-college, 401(k) and Roth IRA.
hamtr 8y ago
Writing release notes for a very active project is pretty hard and time consuming. I can understand why large companies simply say "Bug fixes and improvements" instead of "14 A/B tests that help us understand what to build" I write release notes for Figma and it definitely takes a lot of time, is not perfect, and becoming increasingly challenging.
fpgaminer 8y ago
Seeing this my first thought was "Oh cool, so you format your git commit messages in a certain way, and then this tool will automatically generate changelogs for you." ... but it wasn't that (rather, just good arguments and suggestions). And now I'm wondering if my first thought is a thing? And if so, how it has worked out for users.
- dereke 8y ago
  Not quite a change log but something we've found useful with our clients is https://shippingreport.com https://shippingreport.com It uses PR messages to make a report of what changed. If your PR messages are nice (we use animated gifs to demo changes) then you end up with some really nice reports.
- olivierlacan 8y ago
  People have created million and a half tools to tackle this problem. Just look at the issues and you'll find a ton: https://github.com/olivierlacan/keep-a-changelog/issues?utf8=%E2%9C%93&q=is%3Aissue+tool https://github.com/olivierlacan/keep-a-changelog/issues?utf8... I've tried to refrain from endorsing tools because I feel like they risk making it easy to avoid doing what I actually encourage: curating the notable changes for a release with your mushy human brain for other mushy human brains. I know it's hard, but perhaps it's a good constraint. The idea that you will have the forethought of knowing when writing a commit that it'll be one of the notable entries in your future changelog seems a bit far-fetched to me. And as I tried to explain, the purpose of a commit is not the same as the purpose of a changelog entry, so there's definitely tension in the re-use of copy there. I get the instinct to automate everything. I'm just not sure this is something that should be automated. Now, an assistive tool to help maintainers review commits for missing notable changes within a changelog, that's something I could get behind.
  - bendavis381 8y ago
    I think the issue with automation is it requires a cultural change for most companies / projects. People are very used to small atomic commits and so it’s hard to reduce the noise once parsed into a changelog. To make it work, you need each commit to be as meaningful as a line in the changelog. We use Phabricator and it’s default workflow, so have a clean linear git history. Phabricator already requires strict formatting for any new diff (title, description, testing, etc). It’s built into the culture of any org using Phab to consider commits as meaningful entries in the history of the project. So it would be very straightforward (technically and culturally) to require a simple title prefix ala Changelog (ADDED, FIXED, SECURITY, etc) for each commit and have yourself a automated and meaningful log.
buchanae 8y ago
I wrote github-release-notes to help me stop being lazy about releases. It generates a log based on github PRs. It's not a perfect solution, but it's a place to start, and helps track down the work done and the comments made so I can start writing better notes. A lot of times, the first comment of a PR is a great source of information about a change made (what, why, caveats, etc). [1] https://github.com/buchanae/github-release-notes https://github.com/buchanae/github-release-notes
boramalper 8y ago
I think (a good) changelog is especially important when it comes to closed-source software where you don’t have the opportunity to downgrade easily (from Windows software to mobile applications). For example if you visit the App Store now, you’ll see the many app developers, especially the big ones such as Twitter, Facebook etc., are using the same changelog entry for every, single, update: “Thanks for using X! To make our app better for you, we bring updates to the App Store regularly.” The problem is, this doesn’t tell me anything about what to expect. No, I see that I shouldn’t have anything to worry about because the new features are throughly UX-tested, and as an app end user there is not much to consider anyway (it’s not a framework I’m using in production, right?). The problem is, the changelog matters when Facebook removes messaging functionality to push its users to their new app for some for-profit reason. Changelog matters when your favourite app which has been free for the past couple years have decided that it’s monetisable now and there are intermittent ads in your feed. It matters when they think you don’t need a functionality anymore and proceed to remove it, but you actually do. I think changelog should be enforced far, far more strictly for closed-source software, and especially for those on App Store and Play Store.
- olivierlacan 8y ago
  Couldn't agree more. It's been heartbreaking to see the spread of those rote changelog entries on iOS specifically. Although, meanwhile, large companies like Apple and Google have started including surprisingly high-level and compelling release notes or changelogs to end-users in things like Chrome and Keynote. Smaller shops like Transit, Halide, Darkroom, and many others are going the opposite direction of Twitter and Facebook by offering very detailed and compelling (although sometimes a little too over the top) changelogs for their major releases. One thing I wish people did more, and I feel like I should carve out a section about this on Keep a Changelog: explain exactly what bugs were fixed. I know discrete updaters are becoming more rare with auto-updates, but seeing a specific bug that affected you specifically squashed in a release is perhaps one of the greatest values of changelogs, especially in the case of open source software but also with closed source apps.
  - yjftsjthsd-h 8y ago
acobster 8y ago
This is great. I bookmarked this and will be referring to it consistently as I roll out my first serious open-source project. Thanks!
tmcw 8y ago
As far as I can tell, the autogeneration of changelogs you can do with standard-version https://github.com/conventional-changelog/standard-version https://github.com/conventional-changelog/standard-version and commitzen ( https://github.com/commitizen/cz-cli https://github.com/commitizen/cz-cli ) fulfills the criteria Keep a Changelog wants: right date format, clear notes for breaking changes, and no unnecessary information from irrelevant commits. I've really liked using the two for a variety of systems - the strict commit message formatting and opinionated changelog generation means that the resulting changelogs are pretty darn readable. But ymmv.
- _asummers 8y ago
  Seconding this recommendation. Recently began using them at work and it's improved engineering <--> company communication, as well as engineering <--> engineering communication since I can look at the generated changelog and know exactly what changed there, in ALL commits.
- toyg 8y ago
  These are node-specific tools. Do you know of anything similar but generic? Ideally, one would have something that can be connected to project-management tools rather than github, e.g. Trello: when you mark a checklist or archive a card, the title should go in changelog.
  - StavrosK 8y ago
    I would like something generic as well. I used to use semantic-release[1] but it's a bit too Github-specific for my tastes. [1]: https://github.com/relekang/python-semantic-release https://github.com/relekang/python-semantic-release
JoshTriplett 8y ago
This isn't a changelog, this is a NEWS or release-notes file. Keeping a changelog in version control is an invitation for artificial conflicts on every single commit. (There are ways around that, but better to not keep a traditional changelog, since version control does completely make those obsolete.) But keeping a NEWS file is an excellent practice. And when you send out a release announcement, you can include the corresponding release notes for that release.
- exegete 8y ago
  Yeah, that's the GNU coding standard. Changelog is for developers and bug hunters to see changes to the source. Version control probably takes the place of that now. NEWS is for "user-visible changes worth mentioning". https://www.gnu.org/prep/standards/html_node/Documentation.html#Documentation https://www.gnu.org/prep/standards/html_node/Documentation.h...
  - JoshTriplett 8y ago
    Many people and projects now use NEWS that don't have anything to do with that particular coding standard.
- bostonvaulter2 8y ago
  People generally use those independently now. The meaning of the english word is changing.
mherrmann 8y ago
I view the Changelog as a sales tool: It shows how much work you're doing on the project. I'm developing a cross-platform file manager and try to keep its Changelog very visual [1]. 1: https://fman.io/changelog https://fman.io/changelog
deleted 8y ago
[deleted]
lalos 8y ago
I find it rewarding to clean up my commits, add the work done on the CHANGELOG.md and push the branch for a PR and move on.
crtasm 8y ago
Orfox/Orbot on Android seem to have no changelog, anyone know who I could nudge and/or assist to make one happen? Orfox issues link on f-droid is 404 I notice now.
stared 8y ago
Open source projects are one things. For customer projects it is somewhat rarer to have a decent changelog. Though, I think that Blizzard is awesome at it: http://us.battle.net/sc2/en/game/patch-notes/3-9-0 http://us.battle.net/sc2/en/game/patch-notes/3-9-0 (see both new features, game mechanics balances and bug fixes).
barking 8y ago
He says not to use your repository commit messages as the source for your changelog text. That's exactly what I do use. I started doing this after reading "The Pragmatic Programmer" where it's argued that the DRY principle should apply to everything including documentation. It starts with the bug tracker. So when entering something in that I'll also add the text that I want to appear in the changelog for the user to see (these lines will have a // at the start). When a bug/feature is completed a commit is made and the text in the bug tracker is the commit comment. If the commit comment has a line starting with a // then that line will have another line inserted above it //Bug fix: or // Feature: Finally on building the distributable the changelog is constructed entirely from the lines in the commit messages that start with //
- pacoverdi 8y ago
  That's also what I do. When releasing a new version, I run a script/gradle task/... that: - compiles all commit messages since previous version - filters unwanted messages (according to special tags) - groups them by category (fixes, enhancements, ...) - opens an editor so that a human can prettify the changes - appends the end result to changelog - updates version files - commit changes / git tag / etc EDIT: formatting BTW, I always have to set up those tasks myself. I'm surprised some kind of standard tool does not exist. I guess everybody has their own preferences and no standard really emerged...
  - barking 8y ago
    I like your idea of opening it in an editor to prettify it up. It seems to go at least part way to integration Help Documentation in the process which is something I'd like to achieve
  - cloverich 8y ago
    There are probably a lot of tools that do this. The conventional-changelog[1] is one project, and it links out many others. AngularJS is a good example of a project that's been using that style for quite some time. I ended up using that as inspiration for my own tool (similar to yours) because as you mention, a lot of the pieces can be idiosyncratic to the project, and it turned out to be a relatively straight forward affair anyways. But if I were starting an open-source (node) project today, I'd probably just use the standard-version tools and forget about it. [1]: https://github.com/conventional-changelog/conventional-changelog https://github.com/conventional-changelog/conventional-chang...
nickjj 8y ago
I really like reading hand curated changelogs. In a weird way, sometimes reading a changelog can be more satisfying than using the new version.
RickJWagner 8y ago
Hacker News paydirt! I love it when I find something that directly relates to every day productivity. Kudos to the provider.
mikecx 8y ago
Not sure what the policy is on self-promotion but if you're using Rails, my company wrote https://github.com/CatchRelease/stenographer https://github.com/CatchRelease/stenographer to keep our team up to date on changes. It works by detecting [changelog foo] in your commit message and detects deploys across environments.
spondyl 8y ago
I like to think MMOs can be idolised a little bit when it comes to changelogs. Just check out these patch notes for Patch 4.0 of Final Fantasy XIV: https://eu.finalfantasyxiv.com/lodestone/topics/detail/8937c86379b2124393409732025dac57f23839bc https://eu.finalfantasyxiv.com/lodestone/topics/detail/8937c... Is your average player going to read all this? Probably not but it's still fascinating to see the amount of effort put in for every change, major or minor!
sonnyt 8y ago
Keep a Changelog is a great resource! I actually built a service inspired by it. https://onset.io https://onset.io, check it out. :)

275 points by privong 8y ago

Previous discussions: https://news.ycombinator.com/item?id=12370119 https://news.ycombinator.com/item?id=12370119 (45 comments, 3 years ago) https://news.ycombinator.com/item?id=9054627 https://news.ycombinator.com/item?id=9054627 (43 comments, 4 years ago) See also issues/pull requests in the repo: https://github.com/olivierlacan/keep-a-changelog https://github.com/olivierlacan/keep-a-changelog

simongr3dal 8y ago

Here's hoping this becomes mainstream again. The usual "Make sure to grab the latest update to get the greatest experience. We bring you performance improvements and bug fixes every 14 days" or some annoying joke about dusting code off, taking the trash out and fixing the space-time continuum is getting pretty tired.

craftyguy 8y ago
The most infuriating changelog lines are the ones that just say 'bug fixes' or 'enhancements' (or 'improvements'). Too many change logs have these lines.
- Reedx 8y ago
  True, that doesn't really give much more info than "updated" does.
- ygra 8y ago
  It's a bit annoying to document every single bugfix in a changelog too, though. At least I don't want to read dozens of lines like - Fixed flickering lower-right pixel when hovering over close button with a stylus on devices with more than 300 % UI scaling applied. - Fixed alignment issue in About dialog. - Improved help text for Gizmo frobbing feature. To me a changelog should prominently document changes in function and behaviour. I don't particularly care if an exception message got a typo fixed, but I do care about a new feature, if a login problem for a subset of users has been resolved or a crash under weird circumstances has been fixed.
  - craftyguy 8y ago
    > At least I don't want to read dozens of lines like I must be a crazy user, because I generally like reading through changelogs to see if an update is worth applying because it addresses a specific issue I am having, implements a new interesting feature I want to try, or fixes critical flaws. Luckily, though, public bug trackers are generally a good way to find out at least the 'is my bug fixed' part without the changelog (your issue is closed as 'fixed in X.Y')
  - stared 8y ago
    Yes, it is possible to mention such. It is not important for most users, but super important to ones affected by a given bug. Vide: http://us.battle.net/sc2/en/game/patch-notes/3-9-0 http://us.battle.net/sc2/en/game/patch-notes/3-9-0
- bmalehorn 8y ago
  I have written exactly that kind of changelog. Let me explain why. I write the changelog for a product. In fact I write two changelogs - one for engineers and one for customers. Engineers: - [New Feature] Added ability to ___ - Improved logging on ___ - Fixed a memory leak on ___ Users: - [New Feature] Added ability to ___ Not every change can be explained in one sentence to users. Internal logging? Memory leaks? You're speaking a foreign language. Those entries must be thrown out when making the changelog for users. Eventually, there comes a release when you have thrown everything out. What do you write? "Bug fixes & enhancements".
  - _asummers 8y ago
    You could say something like "fixed stability in account management" or "fixed crash issues across application, improving stability across board". I sympathize with not wanting to go into more detail than would be generally understood by the audience, but there's a large chasm between "bug fixes" and that. If I was experiencing those bugs, I can now expect them to be fixed and I'm now in a better spot if I see them again to say "hey you didn't QUITE fix that in release X". If I see "bug fixes", I can't guess what happened in that release.
  - engerland 8y ago
    We already have our bug tracker for the engineers so why do twice the work? Most engineers don't care once the product is 'out' they only care what they're working on. So we create our change log (they are part of our 'release notes' actually) with only the user in mind but we reference the bug tracker number next to it. This is what we check in to the 'source' for the release notes. Then when we post to the 'outside world' we just remove those tracker numbers (takes a few seconds). That way the engineer can see the 'easy to understand conceptually' bug fix/enhancement and if they want to know more then they can see the Tracker reference and go and look up the 'real meat - with all the discussion and threads etc. For those bug fixes that we 'don't' document we have our source code software.
  - jaxn 8y ago
    We have 4 sections to every changlog release: New, Improved, Fixed, and Internal We maintain a CURRENT_CHANGES.md with those sections. When we do a release, we move the contents of CURRENT_CHANGES to a new entry in RELEASE_NOTES.md. One of these days, I will get around to writing something that displays RELEASE_NOTES in the app, without the Internal section

olivierlacan 8y ago

Since, as okket mentioned, Keep a Changelog has been featured on HN before let me give you... a changelog of what's happened in the project since the last time: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md#100---2017-06-20 https://github.com/olivierlacan/keep-a-changelog/blob/master... Version 1.0 was released introducing: a much cleaner website presenting the guidelines in a more digestible way; 13 new translations; a semi-decent versioning system to help synchronize translations; and a lot of clarifications and updates based on feedback and conversations that occur regularly within the project issues: https://github.com/olivierlacan/keep-a-changelog/issues https://github.com/olivierlacan/keep-a-changelog/issues. I know trying to get ahead of the torrent of critical comments is pointless but let me summarize: yes, I know you think changelogs have been defined before. But you know just as much as I do that most changelogs (or whatever you decide to call them in protest) are terrible and not as helpful to software end-users as they should be. There's been a lot of progress in the past 3 years alone in that regard. It's nearly unthinkable for an open source project to not include a decent changelog for each release. That's good. There are still a lot of smaller, less known, or older projects that could be improved with some basic changelog hygiene. If you're interesting in helping, please do, and if keepchangelog.com can help I'll be glad.

anonytrary 8y ago

Wouldn't proper use of `git rebase --interactive` make changelogs unnecessary?

okket 8y ago
No. The commit history is for the developer perspective, the changelog is for the user perspective. As a user you don't want and need all the details what changed between two releases. As a developer you absolutely need to be able to look this information up.
- opk 8y ago
  I've always thought of the term changelog as being the full list of every single change for the purposes of developers. Back before we had git and used CVS or patches it was necessary to track all changes and this was often in a file named ChangeLog. User relevant changes go in release notes or (a NEWS file if you follow GNU conventions).
  - okket 8y ago
    Changelog is a bit ambiguous, indeed. Release notes would be a more fitting name, but also not ideal IMHO. If you want to know what was changed and when, you need the commit history anyway. Also for bisecting. I'd argue these days changelog and release notes are more interchangeable than changelog and commit history. The 'NEWS' GNU-ism never really caught on, maybe because news does not imply log/history.
slaymaker1907 8y ago
Not everyone who might be interested in your changelog will be a developer. Even developers don't want to go trawling through commit history to know changes at a high level.
- anonytrary 8y ago
  Okay, fine -- but why couldn't you just derive a changelog from version-change commits which are meant for summarizing high-level changes in the version being committed? That way, you don't keep multiple sources of truth for version change information, while still benefiting from keeping a concise changelog without unnecessary commits in it.

todipa 8y ago

## [0.0.5] - 2018-08-28 - [Deprecated] Other system removed all access to GF; APIs not working anymore - [Added] Depression - [Added] Job at fast food retail ## [0.0.4] - 2016-03-13 - [Security] Found security vulnerabilities in GF; she always has a "headache" - [Removed] Job from daily life - fired ## [0.0.3] - 2013-02-12 - [Removed] Man and Lady - [Changed] Lady to Girlfriend - [Changed] Jobs to a higher paying one ## [0.0.2] - 2012-02-29 - [Removed] significant assets from bank account. - [Added] Purchased fast car. - [Deprecated] man and one lady from "hot" list ## [0.0.1] - 2010-11-04 - [Added] two ladies and a man from "hot" contact list - [Added] A job post-college, 401(k) and Roth IRA.

hamtr 8y ago

Writing release notes for a very active project is pretty hard and time consuming. I can understand why large companies simply say "Bug fixes and improvements" instead of "14 A/B tests that help us understand what to build" I write release notes for Figma and it definitely takes a lot of time, is not perfect, and becoming increasingly challenging.

fpgaminer 8y ago

Seeing this my first thought was "Oh cool, so you format your git commit messages in a certain way, and then this tool will automatically generate changelogs for you." ... but it wasn't that (rather, just good arguments and suggestions). And now I'm wondering if my first thought is a thing? And if so, how it has worked out for users.

dereke 8y ago
Not quite a change log but something we've found useful with our clients is https://shippingreport.com https://shippingreport.com It uses PR messages to make a report of what changed. If your PR messages are nice (we use animated gifs to demo changes) then you end up with some really nice reports.
olivierlacan 8y ago
People have created million and a half tools to tackle this problem. Just look at the issues and you'll find a ton: https://github.com/olivierlacan/keep-a-changelog/issues?utf8=%E2%9C%93&q=is%3Aissue+tool https://github.com/olivierlacan/keep-a-changelog/issues?utf8... I've tried to refrain from endorsing tools because I feel like they risk making it easy to avoid doing what I actually encourage: curating the notable changes for a release with your mushy human brain for other mushy human brains. I know it's hard, but perhaps it's a good constraint. The idea that you will have the forethought of knowing when writing a commit that it'll be one of the notable entries in your future changelog seems a bit far-fetched to me. And as I tried to explain, the purpose of a commit is not the same as the purpose of a changelog entry, so there's definitely tension in the re-use of copy there. I get the instinct to automate everything. I'm just not sure this is something that should be automated. Now, an assistive tool to help maintainers review commits for missing notable changes within a changelog, that's something I could get behind.
- bendavis381 8y ago
  I think the issue with automation is it requires a cultural change for most companies / projects. People are very used to small atomic commits and so it’s hard to reduce the noise once parsed into a changelog. To make it work, you need each commit to be as meaningful as a line in the changelog. We use Phabricator and it’s default workflow, so have a clean linear git history. Phabricator already requires strict formatting for any new diff (title, description, testing, etc). It’s built into the culture of any org using Phab to consider commits as meaningful entries in the history of the project. So it would be very straightforward (technically and culturally) to require a simple title prefix ala Changelog (ADDED, FIXED, SECURITY, etc) for each commit and have yourself a automated and meaningful log.

buchanae 8y ago

I wrote github-release-notes to help me stop being lazy about releases. It generates a log based on github PRs. It's not a perfect solution, but it's a place to start, and helps track down the work done and the comments made so I can start writing better notes. A lot of times, the first comment of a PR is a great source of information about a change made (what, why, caveats, etc). [1] https://github.com/buchanae/github-release-notes https://github.com/buchanae/github-release-notes

boramalper 8y ago

I think (a good) changelog is especially important when it comes to closed-source software where you don’t have the opportunity to downgrade easily (from Windows software to mobile applications). For example if you visit the App Store now, you’ll see the many app developers, especially the big ones such as Twitter, Facebook etc., are using the same changelog entry for every, single, update: “Thanks for using X! To make our app better for you, we bring updates to the App Store regularly.” The problem is, this doesn’t tell me anything about what to expect. No, I see that I shouldn’t have anything to worry about because the new features are throughly UX-tested, and as an app end user there is not much to consider anyway (it’s not a framework I’m using in production, right?). The problem is, the changelog matters when Facebook removes messaging functionality to push its users to their new app for some for-profit reason. Changelog matters when your favourite app which has been free for the past couple years have decided that it’s monetisable now and there are intermittent ads in your feed. It matters when they think you don’t need a functionality anymore and proceed to remove it, but you actually do. I think changelog should be enforced far, far more strictly for closed-source software, and especially for those on App Store and Play Store.

olivierlacan 8y ago
Couldn't agree more. It's been heartbreaking to see the spread of those rote changelog entries on iOS specifically. Although, meanwhile, large companies like Apple and Google have started including surprisingly high-level and compelling release notes or changelogs to end-users in things like Chrome and Keynote. Smaller shops like Transit, Halide, Darkroom, and many others are going the opposite direction of Twitter and Facebook by offering very detailed and compelling (although sometimes a little too over the top) changelogs for their major releases. One thing I wish people did more, and I feel like I should carve out a section about this on Keep a Changelog: explain exactly what bugs were fixed. I know discrete updaters are becoming more rare with auto-updates, but seeing a specific bug that affected you specifically squashed in a release is perhaps one of the greatest values of changelogs, especially in the case of open source software but also with closed source apps.
- yjftsjthsd-h 8y ago

acobster 8y ago

This is great. I bookmarked this and will be referring to it consistently as I roll out my first serious open-source project. Thanks!

tmcw 8y ago

As far as I can tell, the autogeneration of changelogs you can do with standard-version https://github.com/conventional-changelog/standard-version https://github.com/conventional-changelog/standard-version and commitzen ( https://github.com/commitizen/cz-cli https://github.com/commitizen/cz-cli ) fulfills the criteria Keep a Changelog wants: right date format, clear notes for breaking changes, and no unnecessary information from irrelevant commits. I've really liked using the two for a variety of systems - the strict commit message formatting and opinionated changelog generation means that the resulting changelogs are pretty darn readable. But ymmv.

_asummers 8y ago
Seconding this recommendation. Recently began using them at work and it's improved engineering <--> company communication, as well as engineering <--> engineering communication since I can look at the generated changelog and know exactly what changed there, in ALL commits.
toyg 8y ago
These are node-specific tools. Do you know of anything similar but generic? Ideally, one would have something that can be connected to project-management tools rather than github, e.g. Trello: when you mark a checklist or archive a card, the title should go in changelog.
- StavrosK 8y ago
  I would like something generic as well. I used to use semantic-release[1] but it's a bit too Github-specific for my tastes. [1]: https://github.com/relekang/python-semantic-release https://github.com/relekang/python-semantic-release

JoshTriplett 8y ago

This isn't a changelog, this is a NEWS or release-notes file. Keeping a changelog in version control is an invitation for artificial conflicts on every single commit. (There are ways around that, but better to not keep a traditional changelog, since version control does completely make those obsolete.) But keeping a NEWS file is an excellent practice. And when you send out a release announcement, you can include the corresponding release notes for that release.

exegete 8y ago
Yeah, that's the GNU coding standard. Changelog is for developers and bug hunters to see changes to the source. Version control probably takes the place of that now. NEWS is for "user-visible changes worth mentioning". https://www.gnu.org/prep/standards/html_node/Documentation.html#Documentation https://www.gnu.org/prep/standards/html_node/Documentation.h...
- JoshTriplett 8y ago
  Many people and projects now use NEWS that don't have anything to do with that particular coding standard.
bostonvaulter2 8y ago
People generally use those independently now. The meaning of the english word is changing.

mherrmann 8y ago

I view the Changelog as a sales tool: It shows how much work you're doing on the project. I'm developing a cross-platform file manager and try to keep its Changelog very visual [1]. 1: https://fman.io/changelog https://fman.io/changelog

deleted 8y ago

[deleted]

lalos 8y ago

I find it rewarding to clean up my commits, add the work done on the CHANGELOG.md and push the branch for a PR and move on.

crtasm 8y ago

Orfox/Orbot on Android seem to have no changelog, anyone know who I could nudge and/or assist to make one happen? Orfox issues link on f-droid is 404 I notice now.

stared 8y ago

Open source projects are one things. For customer projects it is somewhat rarer to have a decent changelog. Though, I think that Blizzard is awesome at it: http://us.battle.net/sc2/en/game/patch-notes/3-9-0 http://us.battle.net/sc2/en/game/patch-notes/3-9-0 (see both new features, game mechanics balances and bug fixes).

barking 8y ago

He says not to use your repository commit messages as the source for your changelog text. That's exactly what I do use. I started doing this after reading "The Pragmatic Programmer" where it's argued that the DRY principle should apply to everything including documentation. It starts with the bug tracker. So when entering something in that I'll also add the text that I want to appear in the changelog for the user to see (these lines will have a // at the start). When a bug/feature is completed a commit is made and the text in the bug tracker is the commit comment. If the commit comment has a line starting with a // then that line will have another line inserted above it //Bug fix: or // Feature: Finally on building the distributable the changelog is constructed entirely from the lines in the commit messages that start with //

pacoverdi 8y ago
That's also what I do. When releasing a new version, I run a script/gradle task/... that: - compiles all commit messages since previous version - filters unwanted messages (according to special tags) - groups them by category (fixes, enhancements, ...) - opens an editor so that a human can prettify the changes - appends the end result to changelog - updates version files - commit changes / git tag / etc EDIT: formatting BTW, I always have to set up those tasks myself. I'm surprised some kind of standard tool does not exist. I guess everybody has their own preferences and no standard really emerged...
- barking 8y ago
  I like your idea of opening it in an editor to prettify it up. It seems to go at least part way to integration Help Documentation in the process which is something I'd like to achieve
- cloverich 8y ago
  There are probably a lot of tools that do this. The conventional-changelog[1] is one project, and it links out many others. AngularJS is a good example of a project that's been using that style for quite some time. I ended up using that as inspiration for my own tool (similar to yours) because as you mention, a lot of the pieces can be idiosyncratic to the project, and it turned out to be a relatively straight forward affair anyways. But if I were starting an open-source (node) project today, I'd probably just use the standard-version tools and forget about it. [1]: https://github.com/conventional-changelog/conventional-changelog https://github.com/conventional-changelog/conventional-chang...

nickjj 8y ago

I really like reading hand curated changelogs. In a weird way, sometimes reading a changelog can be more satisfying than using the new version.

RickJWagner 8y ago

Hacker News paydirt! I love it when I find something that directly relates to every day productivity. Kudos to the provider.

mikecx 8y ago

Not sure what the policy is on self-promotion but if you're using Rails, my company wrote https://github.com/CatchRelease/stenographer https://github.com/CatchRelease/stenographer to keep our team up to date on changes. It works by detecting [changelog foo] in your commit message and detects deploys across environments.

spondyl 8y ago

I like to think MMOs can be idolised a little bit when it comes to changelogs. Just check out these patch notes for Patch 4.0 of Final Fantasy XIV: https://eu.finalfantasyxiv.com/lodestone/topics/detail/8937c86379b2124393409732025dac57f23839bc https://eu.finalfantasyxiv.com/lodestone/topics/detail/8937c... Is your average player going to read all this? Probably not but it's still fascinating to see the amount of effort put in for every change, major or minor!

sonnyt 8y ago

Keep a Changelog is a great resource! I actually built a service inspired by it. https://onset.io https://onset.io, check it out. :)