changelog management

[travi]

first off, thanks for all the effort you put into these and other tools that you maintain. even when there are some pain points, the value i get from your efforts earns a lot of latitude, but i also really appreciate your willingness to discuss opportunities for improvement.

based on your comment from another thread, i'm willing to at least get the issue opened so it can be discussed. my feelings aren't too strong, but maybe my thoughts could be helpful.

I hate monorepos, but it's what makes the most sense for this project.

i'm with you in the distaste for monorepos, at least from the perspective of a consumer. however, i can understand when there are efficiencies gained on the maintenance side. with the effort put in by a maintainer, an efficiency win seems fair even when there are some minor trade-offs that impact consumers.

i mostly spoke up in this case only because of the changelog case. i see that as one of two pain points that i run into consistently with monorepos. the other is the difficulty to file an issue that is for a specific package, which is sometimes outweighed by the simplified ability to file an issue that is not specific to a single package.

i think the pain point for the changelog is mostly noticable because it is approached so differently across various monorepos. if there was a more consistent convention, it may be far less of an issue.

Describe the solution you'd like

From a consistency standpoint, my vote goes toward advertising the details in github release notes. part of this lean is because i'm a heavy greenkeeper user and at least for non-monorepo packages, they are able to show the release notes directly in the PR. this is not handled as well for monorepos, but seems likely to improve.

if i don't find release notes in the greenkeeper PR, i follow the link to the project and check for a release first, in case notes were added that missed timing for inclusion in the PR notes. since this project does still tag the individual releases, would including the notes there be difficult to add?

Describe alternatives you've considered

the CHANGELOG.md is the next place i tend to look. if there is one in the root of the monorepo, i check there first. root changelogs can get pretty noisy for projects with lots of packages/releases though.

i've seen some projects include a separate CHANGELOG.md in the directory of each package, but i could see that being difficult to maintain and it's not always obvious to look for them.

after the changelog, i go back to the releases tab and use the changelog enhancement added by refined github, which then means looking for the details through individual (filtered, at least) commits. it's only after this that i consider digging deeper into the details included in the individual commit bodies.

Additional context

i maintain all of my packages as individual repos, so i do not have experience with lerna or alternative monorepo tools and don't know much detail about the automation available from them.

also, thank you for versioning each package individually rather than syncing the versions across all of the packages :)

[travi]

one other piece that is worth mentioning is commenting on issues that are included in specific releases. i have noticed that you do manually comment at least in some cases, but i wonder if automating something like that further could be helpful.

semantic-release does this really well by automatically commenting on any issues or PRs that it can find that are included in the release that it is publishing, for example: https://github.com/dsmjs/eslint-config-mocha/pull/3#issuecomment-497572393. it also adds a comment when it publishes a pre-release so followers know when it is available in a pre-release and are alerted again once released in a stable version.

[ljharb]

Including the changelog contents for the version in the commit message doesn't seem to show up (like here), but I believe if I include it in the tag annotation (like here) it will show up. If I started doing that consistently, would that help? (currently i include the changelog in the commit message for every package's version bump except enzyme itself, which has a changelog file)

I'm very much not a fan of semantic-release overall, but a PR that adds a "postpublish" script that comments on all PRs that are first included in a version publish of a given package would be worth exploring (I don't really do prereleases, so that doesn't matter much).

I could also maintain a separate per-package changelog, and i could make the root changelog have nothing but a link to the individual ones.

[travi]

If I started doing that consistently, would that help?

having the details included in the github release would be a big help for me at least since it would be more consistent with where i find that information in other projects. since i'm most familiar with semantic-release, i'm used to those notes being added through the github api, but if a tag annotation also accomplishes it, it seems like a workable solution. adding the notes manually through the github ui has the downside of sometimes being slow enough to miss being included in the PR from tools like greenkeeper, but including it as part of the tag sounds like it would avoid that as well.

a "postpublish" script that comments on all PRs that are first included in a version publish of a given package would be worth exploring

i imagine this gets more complicated in a monorepo than what semantic-release does since there would need to be some care taken to identify which issues/PRs are tied to each package. while this would be nice to have, it might be more work than its worth since the github release would already make it more clear what is included.

I could also maintain a separate per-package changelog, and i could make the root changelog have nothing but a link to the individual ones.

this could make sense, but if the details are in the github release, i would then find less value in this. i'd have to defer to others if effort toward this would still be useful

[ljharb]

luckily i wrote my own npm run since command which can determine (largely) which commits apply to a package. However, because I use fast forward merging, it might be trickier to figure out which PR a commit is part of.

[travi]

just to make it visible, i noticed cypress also automatically comments on issues once they are released: https://github.com/cypress-io/cypress/issues/4283#issuecomment-506547085