doc: refactor the changelog by version #6503

jasnell · 2016-05-01T15:14:50Z

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:

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.
Changelog files include an index / table of contents at the top to easily jump to a specific version.
The root changelog file includes an index of the currently supported release lines for easy navigation.
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)
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
Backporting this to the stable branches ought to be trivial.
It's visible in Github.

The downsides of this change are:

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.
Some of the existing tooling for generating release blog posts (and likely others) will need to be updated to understand this new structure.
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 · 2016-05-01T17:19:46Z

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 · 2016-05-01T17:22:17Z

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

jasnell · 2016-05-01T19:45:18Z

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 · 2016-05-01T20:18:33Z

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

jasnell · 2016-05-01T20:21:03Z

@thealphanerd ... fixed!

MylesBorins · 2016-05-01T20:26:11Z

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 · 2016-05-01T20:49:33Z

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 · 2016-05-01T22:16:16Z

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

jasnell · 2016-05-01T22:52:40Z

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:

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.
We'd also add the link to the release changlog in the /CHANGELOG.md at the root.
Commit, release, and so forth.
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.).
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).
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

Fishrock123 · 2016-05-02T19:24:33Z

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 · 2016-05-02T21:35:41Z

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 · 2016-05-03T17:13:35Z

doc/changelogs/CHANGELOG_V010.md

+</tr>
+</table>
+
+* Other Versions


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?

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

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

MylesBorins · 2016-05-03T17:19:03Z

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 · 2016-05-03T17:21:10Z

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

MylesBorins · 2016-05-03T17:27:02Z

no probremo 😄

jasnell · 2016-05-04T21:04:56Z

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 · 2016-05-09T16:47:07Z

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

eljefedelrodeodeljefe · 2016-05-09T17:18:29Z

LGTM

MylesBorins · 2016-05-09T17:34:03Z

@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 · 2016-05-09T17:35:12Z

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

jasnell · 2016-05-10T15:12:41Z

@rvagg ... done.

jasnell · 2016-05-11T02:48:55Z

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

rvagg · 2016-05-11T12:25:53Z

lgtm

Fishrock123 · 2016-05-11T14:24:47Z

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 · 2016-05-11T15:33:47Z

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

jasnell · 2016-05-11T16:01:48Z

Notes added to releases.md

Fishrock123 · 2016-05-11T16:22:58Z

LGTM

The changelog was getting rather huge and difficult to manage. It also wasn't very useful in terms of being able to quickly find specific Node.js versions, or tracking the history for a single major release stream. This reorganizes the changelog by versions separated out over multiple files. An index of the most recent versions is provided in the main log. PR-URL: #6503 Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Robert Lindstaedt <robert.lindstaedt@gmail.com> Reviewed-By: Rod Vagg <rod@vagg.org> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

PR-URL: #6503 Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Robert Lindstaedt <robert.lindstaedt@gmail.com> Reviewed-By: Rod Vagg <rod@vagg.org> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

jasnell · 2016-05-11T16:26:58Z

Landed in c663a6d and 118162e

jasnell · 2016-05-11T16:28:01Z

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

rvagg · 2016-05-12T05:23:51Z

@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 · 2016-05-12T09:49:30Z

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

lpinca · 2016-05-12T10:07:57Z

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.

PR-URL: #6503 Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Robert Lindstaedt <robert.lindstaedt@gmail.com> Reviewed-By: Rod Vagg <rod@vagg.org> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

The changelog was getting rather huge and difficult to manage. It also wasn't very useful in terms of being able to quickly find specific Node.js versions, or tracking the history for a single major release stream. This reorganizes the changelog by versions separated out over multiple files. An index of the most recent versions is provided in the main log. PR-URL: #6503 Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Robert Lindstaedt <robert.lindstaedt@gmail.com> Reviewed-By: Rod Vagg <rod@vagg.org> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

MylesBorins · 2016-10-10T16:24:26Z

@jasnell do we still want to backport this?

jasnell · 2016-10-10T16:49:53Z

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

jasnell added doc Issues and PRs related to the documentations. meta Issues and PRs related to the general management of the project. labels May 1, 2016

MylesBorins reviewed May 3, 2016
View reviewed changes

jasnell added the ctc-agenda label May 3, 2016

rvagg mentioned this pull request May 4, 2016

Node.js Foundation Core Technical Committee (CTC) Meeting 2016-05-04 #6567

Closed

jasnell added wip Issues and PRs that are still a work in progress. and removed ctc-agenda labels May 4, 2016

jasnell force-pushed the changelog-partition branch 3 times, most recently from b588923 to 1489521 Compare May 9, 2016 16:46

jasnell removed the wip Issues and PRs that are still a work in progress. label May 9, 2016

jasnell force-pushed the changelog-partition branch from 472ad25 to ba9037f Compare May 10, 2016 15:11

jasnell mentioned this pull request May 11, 2016

Update changelog tool for https://github.com/nodejs/node/pull/6503 nodejs/nodejs.org#733

Closed

doc: update releases.md with new changelog structure

cb2208d

jasnell closed this May 11, 2016

jasnell added lts-watch-v4.x labels May 11, 2016

evanlucas mentioned this pull request May 17, 2016

2016-05-17, Version 6.2.0 (Stable) #6810

Merged

doc: refactor the changelog by version #6503

doc: refactor the changelog by version #6503

Conversation

jasnell commented May 1, 2016 • edited Loading

Checklist

Affected core subsystem(s)

Description of change

Fishrock123 commented May 1, 2016 • edited Loading

Fishrock123 commented May 1, 2016

jasnell commented May 1, 2016

MylesBorins commented May 1, 2016

jasnell commented May 1, 2016

MylesBorins commented May 1, 2016 • edited Loading

jasnell commented May 1, 2016

MylesBorins commented May 1, 2016

jasnell commented May 1, 2016

Fishrock123 commented May 2, 2016 • edited Loading

jasnell commented May 2, 2016

MylesBorins May 3, 2016

Choose a reason for hiding this comment

jasnell May 3, 2016 • edited Loading

Choose a reason for hiding this comment

MylesBorins May 3, 2016

Choose a reason for hiding this comment

MylesBorins commented May 3, 2016 • edited Loading

jasnell commented May 3, 2016

MylesBorins commented May 3, 2016

jasnell commented May 4, 2016

jasnell commented May 9, 2016

eljefedelrodeodeljefe commented May 9, 2016

MylesBorins commented May 9, 2016

jasnell commented May 9, 2016

jasnell commented May 10, 2016

jasnell commented May 11, 2016

rvagg commented May 11, 2016

Fishrock123 commented May 11, 2016

jasnell commented May 11, 2016

jasnell commented May 11, 2016

Fishrock123 commented May 11, 2016

jasnell commented May 11, 2016

jasnell commented May 11, 2016

rvagg commented May 12, 2016

lpinca commented May 12, 2016

lpinca commented May 12, 2016

MylesBorins commented Oct 10, 2016

jasnell commented Oct 10, 2016

jasnell commented May 1, 2016 •

edited

Loading

Fishrock123 commented May 1, 2016 •

edited

Loading

MylesBorins commented May 1, 2016 •

edited

Loading

Fishrock123 commented May 2, 2016 •

edited

Loading

jasnell May 3, 2016 •

edited

Loading

MylesBorins commented May 3, 2016 •

edited

Loading