Skip to content

doc: refactor the changelog by version

Rodrigo Muino Tomonari requested to merge github/fork/jasnell/changelog-partition into master
Checklist
  • documentation is changed or added
Affected core subsystem(s)

doc (changelog)

Description of change

/cc @nodejs/documentation @nodejs/ctc @TheAlphaNerd

This is a proposed refactoring of the changelog. As reported by https://github.com/nodejs/node/issues/6363 and https://github.com/nodejs/node/issues/6358, the changelog had grown too large to be visible on github. It was also almost completely unusable in terms of quickly finding information for any single release or tracking changes for specific release streams. A temporary fix was landed in https://github.com/nodejs/node/pull/6337 just to make sure the most recent changelogs could be viewed in Github.

To see how the proposed change would look in practice, visit: https://github.com/jasnell/node/blob/changelog-partition/CHANGELOG.md

This PR reorganizes the changelog by release stream, and brings the following benefits:

  1. Changelogs are organized by release stream. So if a user wants to track only changes for v4, for instance, they can look at the CHANGELOG_V4.md. If the user wants to track only changes for v0.12, they can look at CHANGELOG_V012.md.
  2. Changelog files include an index / table of contents at the top to easily jump to a specific version.
  3. The root changelog file includes an index of the currently supported release lines for easy navigation.
  4. The changelogs include clear indication about LTS support (if you mouse over the release line headers in the index on the main changelog page you'll even see an indication of how long the release is expected to be supported)
  5. The changelog files support a less complicated anchor tag for each release, to view the change log for version 4.2.0, for instance, you can link to CHANGELOG_V4.md#4.2.0
  6. Backporting this to the stable branches ought to be trivial.
  7. It's visible in Github.

The downsides of this change are:

  1. Existing links to the original changelog page are broken. This is largely unavoidable if we split this file up because markdown does not provide us with a way of automatically redirecting users to the right page. This limitation is addressed in the text and is a primary reason the simplified index is provided.
  2. Some of the existing tooling for generating release blog posts (and likely others) will need to be updated to understand this new structure.
  3. Those of us who do releases will have a bit more work to do around the changelog to make sure the additional styling and indexes are updated. Information on this would be added to the releases document.

Merge request reports