Changelogs without reference to the actual source changes are completely and utterly useless.
Changelogs with reference to the actual source changes are support natively by git. They're called commits.
Keep a Changelog
31–40 of 53 posts
Re: Keep a Changelog
#32I've been hand-writing a CHANGELOG.md file, in each of my repos, for a long time. Before that, I used to keep it as a section of my README.md file.
I got used to the second file, after using CocoaPods. I don't really use CocoaPods anymore, but they would render the CHANGELOG.md file in a separate tab, which was nice. I don't think anyone else does that.
I think a hand-written changelog is better than a semantically-generated one, because it connects the developers' mindset to the consumer (usually, another developer). It says "These are the aspects of this release that I think are important."
A semantically-written changelog doesn't actually need to be kept. It can be auto-generated on demand. As long as the developer keeps good commit notes, with things like issue numbers, then this could be useful.
Re: Keep a Changelog
#33Semantic pull requests [0] + conventional-changelog [1] + squashing PRs and you get almost the same results (and more) with great automation and self-documentation for the whole process: * you'll never forget to add something to changelog * you get links to PRs in your changelog * it's much faster to make edits to PR messages compared to editing files * outside contributors get familiarized with the practice much fas…
It always depends on your users. Such a changelog is suitable for stuff other developers use, but not for end users. But it is a _way_ better starting point to write a changelog that 'usual' commit messages or PR descriptions.
How can I, as a user, know if bug x, or issue y is resolved, without a changelog?!
Re: Keep a Changelog
#34Or you could just filter the commit history and use squash instead of merge.
That's better than nothing, but code commits and changelogs have different use cases. Commit logs are for all changes, regardless of size or context. Whereas changelogs are for consumer-facing changes.
That's why you filter it...
Re: Keep a Changelog
#35The approach I like to take is to curate issues and PR with semantic titles and organize them by label ("bug", "enhancement", etc) or linking PRs to an already curated issue. This way automation can use these to generate the changlog for me on each release based on closed issues and unlinked PRs since the last release.
We wrote Chronicle to do that automation for us: https://github.com/anchore/chronicle .
The nice thing about this... since you typically curate issues during the development process anyway, if you're doing that right then you get a nice looking changlog for free! We use this approach with our core tools, Syft and Grype (some changlog examples: https://github.com/anchore/syft/releases/tag/v0.31.0 and https://github.com/anchore/grype/releases/tag/v0.26.1 ).
Always happy to hear new feature ideas and possible customizations for Chronicle (put in an issue and let's chat )!
Re: Keep a Changelog
#36Semantic pull requests [0] + conventional-changelog [1] + squashing PRs and you get almost the same results (and more) with great automation and self-documentation for the whole process: * you'll never forget to add something to changelog * you get links to PRs in your changelog * it's much faster to make edits to PR messages compared to editing files * outside contributors get familiarized with the practice much fas…
I'm having trouble figuring out what a "semantic pull request" is from that link, it's not a concept I've heard of before, and I'm interested. I mean, i assume it's some conventions for what goes in PR message, but what are they? Is there a better link?
In general, as a developer-consumer of them, I have found automatically-generated-from-commits changelogs to be not so useful, but I don't know if I've experienced any using the conventions you are recommending (which I dont' understand!).
In the small projects I write, I include links to the PR in the manually created CHANGELOG (the delta of which is part of the PR) simply by making the PR, then making another commit/ammend in the PR to add it's own url to the CHANGELOG. These are some extra steps, it's true.
Re: Keep a Changelog
#37Earlier quoted context omitted.
May I ask you why you want to squash every branch ? What is the size of the resulting commit (in terms of average modified files, lines of code) ?
I've shared this anecdote elsewhere but it's my go-to example. We recently had a new engineer join our team, we gave them a small piece of work related to a bigger feature we had completed months before they arrived. They tracked the feature back to the squashed PR commit, which of course referenced the Github PR URL- in there they had the engineer's summary and implementation caveats, the review comments from the re…
I don't think I understand what "squashing PR branches" means (a github feature I haven't noticed?), but:
> The real benefit here is that Github puts the PR URL into the squashed commit message.
While not in the commit message, github will show you the PR a commit is part of in it's commit view regardless, also for every commit in a PR whether it's one commit or 50. Which I do find invaluable for tracing the documentation of a change, agreed! Not everyone knows about this feature (I don't think it's been there forever) in github UI.
Eg notice the `#279` included in this github commit UI display (the PR was, I'm pretty sure, not "squashed").
https://github.com/traject/traject/commit/10339e774e92e57f44...
Re: Keep a Changelog
#38Re “ Regional date formats vary throughout the world and it's often difficult to find a human-friendly date format that feels intuitive to everyone. The advantage of dates formatted like 2017-07-17 is that they follow the order of largest to smallest units: year, month, and day.”
I disagree. ISO 8601 is great for machine readable dates. For human readable dates I prefer to spell the month out.
17 July 2017 is more readable than 2020-07-17. Yes it is in English but if your audience is in English and the rest of your content is in English then it’s fine.
Re: Keep a Changelog
#39Re “ Regional date formats vary throughout the world and it's often difficult to find a human-friendly date format that feels intuitive to everyone. The advantage of dates formatted like 2017-07-17 is that they follow the order of largest to smallest units: year, month, and day.” I disagree. ISO 8601 is great for machine readable dates. For human readable dates I prefer to spell the month out. 17 July 2017 is more re…
DD-MMM-YYYY is also very readable.
Re: Keep a Changelog
#40Re “ Regional date formats vary throughout the world and it's often difficult to find a human-friendly date format that feels intuitive to everyone. The advantage of dates formatted like 2017-07-17 is that they follow the order of largest to smallest units: year, month, and day.” I disagree. ISO 8601 is great for machine readable dates. For human readable dates I prefer to spell the month out. 17 July 2017 is more re…
17 July 2017 removed ambiguity but still feels a bit awkward for US people.