Clearer changelogs #28
Conversation
The companion to the [comprehensive changelogs RFC](#27)
|
|
||
| # Unresolved questions | ||
|
|
||
| Are the benefits of additional descriptions worth the extra work? |
There was a problem hiding this comment.
I feel like they're one of the biggest benefits of doing this. But we can do everything else first, and then follow up with the additional descriptions at a later date.
There was a problem hiding this comment.
I would agree with this. In my mind we should aspire to have a changelog that people take screenshots of and share — Yelp is really good at this, for example — because it A) encourages people to read them, and B) helps ensure that the content is actually useful.
We don't necessarily need to hit that mark, but if we start with that goal in mind and scale back from there, I think we'll end up in a good place.
There was a problem hiding this comment.
Just to clarify - is the question about extra work do adjust tools or extra work for every PR to compose concise/precise additional description?
| ## [2.0.107](https://github.com/gatsbyjs/gatsby/compare/[email protected]@2.0.107) (2019-01-31) | ||
|
|
||
| - 🐛 **Bug Fix** - **gatsby:** always respond with index html without checking path [#11400](https://github.com/gatsbyjs/gatsby/issues/11400) ([@this-excellent-contributor](https://github.com/this-excellent-contributor)) | ||
| - 🐛 **Bug Fix** - **gatsby:** check type when querying by ID [#11448](https://github.com/gatsbyjs/gatsby/issues/11448) ([@this-excellent-contributor](https://github.com/this-excellent-contributor)) |
There was a problem hiding this comment.
Will changelogs always be one package? Or is it possible that this list would include bug fixes for multiple packages?
If it's multiple packages, I think my preference would be to group by package, then fix type, e.g.:
- gatsby
- 🐛 Bug Fix — ...
- 🚀 Feature — ...
- gatsby-source-graphql
- 🧹 Chore — ...
If it's single-package-per-changelog, I'm into this.
There was a problem hiding this comment.
For now they will probably stay 1 changelog per package. The package in this example (and what we use currently) is conventional commit scope (prefix(scope):) (but we could discard that if scope is the same as package name - at least I think it's doable)
There was a problem hiding this comment.
you can create a changelog formatter yourself where you can omit prefix and scope when creating it so we're good.
|
|
||
| Add a 'no context' description to each PR before merging it. This would allow us to automatically include these descriptions in the changelog. | ||
|
|
||
| A 'no context' description is a self contained description that can be understood without referencing the code or an external issue. |
|
|
||
| # Unresolved questions | ||
|
|
||
| Are the benefits of additional descriptions worth the extra work? |
There was a problem hiding this comment.
I would agree with this. In my mind we should aspire to have a changelog that people take screenshots of and share — Yelp is really good at this, for example — because it A) encourages people to read them, and B) helps ensure that the content is actually useful.
We don't necessarily need to hit that mark, but if we start with that goal in mind and scale back from there, I think we'll end up in a good place.
|
|
||
| ### Credit pull request author(s) | ||
|
|
||
| Contributors are nice, let's credit them for their work. |
|
|
||
| # Detailed design | ||
|
|
||
| Here's a list of changes implemented in the proposed example above. |
There was a problem hiding this comment.
Question about this: are we able to define this template for existing tools? Or are we putting ourselves in a position to write custom changelog generation?
There was a problem hiding this comment.
We would need to create (probably fork from default we use now) changelog preset. Presets do some processing on commits and have handlebars templates.
I've been experimenting with adjusting default preset and this isn't very time consuming task (I would say few hours to implement these changes). Here's output of my forked preset https://github.com/pieh/lerna-playground/blob/master/packages/package-b/CHANGELOG.md (extra paragraph added to entry, credits to PR author, having actual entries for commits other than feat:, fix:).
Changelog preset I used is in https://github.com/pieh/conventional-changelog-pieh (no code review plz - it's messy PoC)
There was a problem hiding this comment.
Okay, cool. If it's not a huge amount of code to manage, I'm happy. I'd love to see better changelogs that are suited to our specific needs for sure.
|
Not sure how this fits in (or if it doesn't) but related to version bumping: I've regularly seen patch bumps for features. The change log indicates a feature was added but the minor version wasn't bumped...only the patch version. This hasn't cased major issues cause things weren't breaking but I have seen certain functionality change and people be surprised. Here's an example: https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-manifest/CHANGELOG.md#2025-2019-03-27 It's happened multiple times on the |
|
I just saw the node community uses tags to indicate what kind of change ( SEMVER_MAJOR, SEMVER_MINOR, SEMVER_PATHCH). Maybe that'd be helpful in making sure patches get bumped correctly. |
|
We've had a lot of conversations about semver, but as of right now Gatsby does not follow semver. My preference would be to adopt it, but the cost of adoption is non-trivial — last I saw there was disagreement on whether the trade-offs were worth the switch. Whether or not we should adopt semver is going to be a huge discussion, so it's probably worth its own RFC. |
|
@jlengstorf Good to know. Is this documented for folks to understand? That could be good info for those wondering if they can update. |
To be clear, Gatsby won’t introduce any breaking changes without bumping the major version. So it’s always safe to update within the same major version — any backward compatibility problems with a 2.x upgrade would be a bug. That being said, our versioning is not documented anywhere that I’m aware of. Maybe @pieh or @DSchau knows more? |
|
All were not doing is trying to figure out whether a given change is a bug fix or a "new feature" as the distinction is pretty small. Basically we release minors when something is particularly noteworthy. This is fine since by default in people's package.json, they get all updates that aren't major releases. So in effect, semver these days is major vs not major releases so we are following semver by not releasing breaking changes on minor/patch releases. |
|
Anything going on with this? I personally have a hard time figuring out what exactly has improved, since much of the individual package changelongs are "nothing has changed" spam. So I'd love to see that part condensed: TIA |
View formatted
I split this out from its companion RFC as it felt unwieldy jamming this all into one document.