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.

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

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.

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

@thealphanerd ... fixed!

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.

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 ;-)

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

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

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?

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.

nit addressed, LGTM.

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

edit: waiting on the ctc to discuss

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

no probremo 😄

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.

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

LGTM

@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

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

@rvagg ... done.

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

lgtm

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?

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

Notes added to releases.md

LGTM

Landed in c663a6d and 118162e

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

@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.

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

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.

@jasnell do we still want to backport this?

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