docs(FAQ): explain why is chore entries not in my CHANGELOG #195
Conversation
| @@ -307,6 +307,14 @@ Although this will allow each commit to be included as separate entries in your | |||
|
|
|||
| For this reason, we recommend keeping the scope of each PR to one general feature or fix. In practice, this allows you to use unstructured commit messages when committing each little change and then squash them into a single commit with a structured message (referencing the PR number) once they have been reviewed and accepted. | |||
|
|
|||
| ### Why is `chore`, `style`, `refactor`, `docs`, `ci` or `build` entries not in my CHANGELOG? | |||
|
|
|||
| TL;DR: Those entries don't make any different to your end-users, unless there's a BREAKING CHANGE. | |||
There was a problem hiding this comment.
Maybe change this line to this?
These entries shouldn't make any difference to your end-users, unless there's a BREAKING CHANGE, in which case the entry **will** be included in the CHANGELOG.|
|
||
| TL;DR: Those entries don't make any different to your end-users, unless there's a BREAKING CHANGE. | ||
|
|
||
| Typically, commits marked as chore do not end up in the CHANGELOG by default. Since the CHANGELOG file is always included in the published package, the idea is to strike a balance between including the important changes (in an easy to read/render format) and keeping the file to a reasonable size. If all changes were included, it would essentially duplicate the entire git log. |
There was a problem hiding this comment.
Can we add this link?
Since the CHANGELOG file is [always included](https://docs.npmjs.com/files/package.json#files) in the published package...|
|
||
| Typically, commits marked as chore do not end up in the CHANGELOG by default. Since the CHANGELOG file is always included in the published package, the idea is to strike a balance between including the important changes (in an easy to read/render format) and keeping the file to a reasonable size. If all changes were included, it would essentially duplicate the entire git log. | ||
|
|
||
| The only reason that chore ended up in the CHANGELOG is because it was also marked as a BREAKING CHANGE, which is a little odd but understandable. |
There was a problem hiding this comment.
One more suggestion, let's change this line to:
The only reason a chore (or similar entry) will end up in the CHANGELOG is if it is also marked as a BREAKING CHANGE.
|
Blocked by #219 |
|
@stevemao this documentation seems reasonable, but my temptation is to potentially move it into a We've taken this approach with yargs (splitting docs across a few files in |
|
I think it's still worth adding 👍 |
|
@bcoe I'm not in Slack anymore, but this PR still looks good to me. I feel the explanation will really help our community understand the versioning behavior of |
|
Hey everyone, I was watching #280 which now refers to this ticket. Just to add my two cents to the discussion: We do have some smaller libraries, where we don't always add new features. Sometimes we just implement Take this very PR for example. If you would release this PR maybe along with some other documentation improvements, but no feature, then there would be a release without any release notes. This seems odd to the end-user. Of course the workaround would be to just label such changes as a fix, but it would still be nice if I could configure the types of changes that go into the changelog based on my use case. I would assume this configuration would be different, depending on the type and size of the library/project/use case someone is working on. Regarding difference to the git log: In our case, typically many commits make up a PR. The PR is then merged or squash merged with a conventional commit message. So this would be one entry in the change log per PR and not one entry per commit. |
|
@ruhkopf want to create a ticket for this feature? I'd rather make this configurable than land these docs explaining why we don't support chores, to be honest. |
|
@bcoe at the moment it is just a config file (not an option). |
|
@stevemao what project does this config file live in; I think it would be nice to make it more easily configurable. For context, @JustinBeckwith and I are exploring using conventional commit messages for some of the libraries we're working on. However, doing so will likely require a bit more flexibility in CHANGELOG generation, and some additions to the specification. |
|
https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#config |
|
There used to be a PR on adding a new preset to make angular-like conventions easy to config. I think we should create one and use it more. |
|
@stevemao I agree, do you think we could make this the preset that we use for How would this preset be different than others (what would make it more configurable)? |
yes, and even angular config can be based on it On top of my head, we can just list types that need to goto the CHANGELOG. BREAKING CHANGE keywords to mark this is important. Maybe some aliases (EG: |
|
since #323, you can now configure whatever commit types you'd like to show up in your CHANGELOG \o/ |
I was surprised to see people asking for this since it made sense to me when I looked at it the first time. But too many people asking for it so maybe worth to add this? Mostly I copied @nexdrew's comment in issue #135.
Closes #135