Besu changelog management

The file is ever-growing https://github.com/hyperledger/besu/blob/main/CHANGELOG.md

Contains outdated links and content (eg documentation updates from when besu docs were part of besu repo). This results in PRs such as https://github.com/hyperledger/besu/pull/7558 which are updating old links

Propose to remove old content from the changelog

  • first, remove previous releases from the changelog and keep Unreleased section only
  • add changes to the changelog with PRs as we do now under Unreleased
  • when we do a release, the contents of the changelog become the release notes for that release, and the changelog gets wiped - Unreleased section is empty again

One reason for not doing this is that it makes github the only option for users to see the release notes, however now we use github to serve the releases themselves so that reason seems less compelling.

One advantage of having the changelog in a single file is that it's easy to search.

An alternative proposal which would remediate the broken link issue - remove docs updates from the changelog - https://github.com/hyperledger/besu/pull/7562

  • No labels

3 Comments

  1. Simon Dudley

    Happy to cease maintaining it and rely on github release notes. As Gabriel suggested, it might be good to archive the old releases.
    Whether or not we maintain this archive for future releases, I think it's worth keeping the current changelog file in archive form in the repo since it predates the start of github releases.

  2. Fabio Di Fabio

    Independently of where we decide to keep the changelog, I think we can get this as an opportunity to improve the way it is generated, since today it is opt-in and it happens that some PRs that should have a changelog entry are merged without it, so for example Github can autogenerate a changelog, or we can implement our own solution, maybe based on the example of some other projects. 

  3. Matthew Whitehead

    I'm broadly in favour of making it more automated. My only comment would be that it can be useful to have a way for an individual to highlight something specific in a release that might get hidden in the description of a PR and missed by someone picking up the new release. E.g. if a feature is marked as deprecated and removed in the future, or there's a behaviour quirk worth being aware of. I also like the way the current change log has a place for a general overview of the release. For example, "this release is mainly of interest to public node runners".