Comment by epage | Hacker News Reader

Comment by epage | Hacker News Reader

My problem with maintaining a changelog during development is it can serve as a source of merge conflicts. Instead, I follow Covnentional Commit style and manually write my changelog entries based on the commits. I have a tool [0] that can show me the relevant commits for a package in my repo and automates the entire release process, including doing sanity checks.

I also feel like releasing from CI is hard, especially if you have multiple packages in a repo [1], including

- You can't as easily introspect the process

- You can't as easily recover from failure

- Getting a lot of the nuance right, like handling releases concurrent to merging of PRs, is difficult

- When the workflow is an ever-present "release PR" that you merge when ready has issues with selecting which packages to release and at what version

I have been considering making a tool to generate changelogs from fragments. Been keeping notes at https://github.com/epage/epage.github.io/issues/23

[0]: https://github.com/crate-ci/cargo-release

[1]: https://github.com/MarcoIeni/release-plz/discussions/1019

I don't really like writing the change log automatically from commits. I think those both have a slightly different audience and thus need different wording.

I know the frustration of merge conflicts on the change log file.

Right now, I'm creating change logs by hand which is time consuming to do on release time. I'm considering switching to using towncrier or something similar, where you have a changes dir with one file per change for creating change logs --> https://towncrier.readthedocs.io/

The towncrier approach is similar to what we do at work. We have the addition that the individual changelog files say their scope (major, minor, or patch), and we use that to automatically compute the next version number.

  version.txt
    1.0.0
  CHANGELOG
    # 1.0.0
    * Initial release
  changelogs/add-foobar-api.md
    minor: Add a new API call `foobar`
  changelogs/improve-baz-perf.md
    patch: Improve the performance of the `baz` API call

In the changelog compilation step it works out that the largest scope is minor, so the version of the next release is bumped from 1.0.0 to 1.1.0, and you end up with:

  version.txt
    1.1.0
  CHANGELOG
    # 1.1.0
    * Add a new API call `foobar`
    * Improve the performance of the `baz` API call

    # 1.0.0
    * Initial release

It works great, especially for large teams. You don't end up with lots of merge conflicts on the CHANGELOG file. The people writing the change get to describe the scope of the change (and that can be reviewed in the PR), rather than the person doing the release having to guess from the descriptions. Developers never have to worry about whether someone else has already bumped the version number or not.

Reply on news.ycombinator.com