doc: refactor the changelog by version

[jasnell]

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 #6363 and #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 #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.

[Fishrock123]

We can't get rid of CHANGELOG.md. That will break too many links.

Imo it should contain only the headers (for links) which then contain a link to where it actually is. A redirect, per se. Maybe the latest LTS & Current streams should have their actual contexts in there too and only be archived later? That would be the most user-friendly.

EDIT: github diff made it look like it was deleted... I'd be ok with this format but we should also but the headers with links in the content below that so that existing links to it actually work.

It's also quite confusing to have the main changelog by date and these by version though. I'd like to hear more discussion on that personally.

[Fishrock123]

v5 changelog rendered: https://github.com/jasnell/node/blob/changelog-partition/doc/changelogs/CHANGELOG_V5.md

[jasnell]

We can't get rid of CHANGELOG.md. That will break too many links.

This certainly does not get rid of the root CHANGELOG.md.

I'd be ok with this format but we should also but the headers with
links in the content below that so that existing links to it actually work.

Very well. Done.

It's also quite confusing to have the main changelog by date and these by version though.

The main changelog is not ordered by date. If you look at the new changelog page that I linked to in the PR description it is organized by version, just like the individual version pages.

Per your request, I've added back in the original headers with links to the new locations. I preserved the existing date order of those. I personally find it less appealing but it works I guess.

[MylesBorins]

@jasnell it looks like you have the wrong date in the v5 changelog. It says June 2015 not 2016

[jasnell]

@thealphanerd ... fixed!

[MylesBorins]

So overall I like the direction this is heading... my only contention would be whether or not the latest release line should be in the primary changelog. Although that could get weird between release streams.

It seems to me like we should likely be keeping the release streams specific changelog as the root directory changelog in that release. e.g. doc/CHANGELOG_V4.md would simply be CHANGELOG in v4.x. This would make cherry picking the changelog changes a bit more complicated... but making a patch and changing the path would not be terribly difficult, this could easily be make a bash one-liner.

I would like to see this change come with at least a first pass at documenting the new changelog process. I think that we are most of the way there (in the main changelog), but it should likely address the difference in the changelog between release streams if there will be one.

[jasnell]

I went with the current approach because it would be marginally easier to manage the changelog edits across streams (e.g. v6 changes would always go to the CHANGELOG_V6 file, v4 changes would always go to the CHANGELOG_V4 file). Doing it this way means we don't have to move things around when we do a new major, we just create a new doc/changelog/CHANGELOG_V* file, add the column to the table on CHANGELOG.md and off we go. In the v5.x branch, we'd only pull back changes to CHANGELOG_V5, CHANGELOG_V4, CHANGELOG_V012 and CHANGELOG_V010 files.

To be honest, I think it should actually simplify the cherry picking of edits a tad easier. But that's just my opinion ;-)

[MylesBorins]

I'm up for seeing how that works and iterating if it shows to have ways to improve 😄

[jasnell]

Fairly simple: Let's say we do another release in v5. The current process is to update the changelog.md in the v5.x branch and cherry pick that commit to master's changelog.md. The process would be no different here:

1. We'd add the new changelog entry to /doc/changelogs/CHANGELOG_V5.md, being sure to add the relevant link to the index at the top.
2. We'd also add the link to the release changlog in the /CHANGELOG.md at the root.
3. Commit, release, and so forth.
4. The release commit is cherry-picked back to master as we currently do. The new v5 change log is dropped into /doc/changelogs/CHANGELOG_V5.md and the index entries are updated in CHANGELOG.md master (at worst this would require a -3 merge.).
5. Cherry pick that commit into v6.x, which again, at worst would be a -3 merge on /CHANGELOG.md. The only edits actually being made on /CHANGELOG.md are to the first and second items in any given index column (to make the new release the current -- bold print).
6. A v0.10 release would cherry pick into master, v6, v5, v4 and v0.12
7. A v0.12 release would cherry pick into master, v6, v5, and v4
8. A v4 release would cherry pick into master, v6, v5
9. A v5 release would cherry pick into master, v6
10. A v6 release would cherry pick into master

[Fishrock123]

This seems fine to me.

my only contention would be whether or not the latest release line should be in the primary changelog. Although that could get weird between release streams.

I'd be inclined to agree with this, latest Current and latest LTS line maybe?

[jasnell]

I see no real value in that and it would just making cherry-picking and updating for each release more difficult. The release announcements can be made to point to the relevant CHANGELOG_V#.md files where the content would either end up just being duplicated or we'd have to throw in an extra step to move it. -1 to having the latest release line changlog in the root changelog file.

[MylesBorins]

This is what I was referring to before, that will be broken in release streams.

I don't think we need to include the links to the other change logs... thoughts?

[jasnell]

Why would these be broken? when we port this to the other release streams we simply pull out the links that don't apply to that stream :-) ... so in v4.x, there wouldn't be links to the v5 or v6 pages... update: or we'd make those point to the right branches

[MylesBorins]

Reasonable... and then when we port changes from releases back to master there will be no conflicts... makes sense

[MylesBorins]

nit addressed, LGTM.

I'll be landing this in the afternoon as long as no one objects

edit: waiting on the ctc to discuss

[jasnell]

@thealphanerd ... hold off on landing this one until @nodejs/ctc has had more time to review please :-)

[MylesBorins]

no probremo 😄

[jasnell]

The CTC discussed this and had no objections to this moving forward. I will be doing a bit more work on it, however. Putting the in progress label on. Will remove it when I think it's ready to go.

[jasnell]

@nodejs/ctc @nodejs/documentation... this should be ready to go. PTAL

[eljefedelrodeodeljefe]

LGTM

[MylesBorins]

@jasnell is there a reason to keep the CHANGELOG archive if it is a dupe of the data found in the other changelogs?

Other than that nit LGTM

[jasnell]

@thealphanerd ... it's not a dup. The changelog archive contains everything pre-io.js.

[jasnell]

@rvagg ... done.

[jasnell]

@nodejs/ctc ... Please take a final look. If there are no further comments or nits by tomorrow I will get this landed.

[rvagg]

lgtm

[Fishrock123]

I'm not sure if this was addressed:

@jasnell mind describing the workflow for how we edit these for a release? That info will need to be added to https://github.com/nodejs/node/blob/master/doc/releases.md#3-update-changelogmd

I'm seeing something above, but I'm not following:

• A v0.10 release would cherry pick into master, v6, v5, v4 and v0.12
• A v0.12 release would cherry pick into master, v6, v5, and v4
• A v4 release would cherry pick into master, v6, v5
• A v5 release would cherry pick into master, v6
• A v6 release would cherry pick into master

Why? We've only fully maintained the changelog in master until now. Perhaps we should add language stating that it is only fully maintained in master?

[jasnell]

@Fishrock123 ... #6503 (comment) describes the workflow. Are you wanting me to add it to the releases.md doc in this PR?

[jasnell]

Notes added to releases.md

[Fishrock123]

LGTM

[jasnell]

Landed in c663a6d and 118162e

[jasnell]

Marking this for LTS watch and land-on for all streams. It will need to be backported, however. I will do so soonish.

[rvagg]

@jasnell how do you plan on handling the differences between 0.12 and v4 where we switched from ChangeLog to CHANGELOG.md and went full markdown including a rough translation of old entries? Do you want to fully backport all of the markdownage? I'm cool with that fwiw, we'd need to get the release script updated on nodejs/nodejs.org so perhaps drop a note in there if/when you do that.

[lpinca]

@rvagg, @jasnell already did that. See nodejs/nodejs.org#733.

[lpinca]

It would be nice if the markdown changelog could be backported to 0.10 and 0.12 as it will simpliy the release script a bit.

[MylesBorins]

@jasnell do we still want to backport this?

[jasnell]

Eventually. I'd say it's a fairly low priority.