Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: refactor the changelog by version #6503

Closed
wants to merge 2 commits into from

Conversation

jasnell
Copy link
Member

@jasnell jasnell commented May 1, 2016

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.

@jasnell 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
@Fishrock123
Copy link
Contributor

Fishrock123 commented May 1, 2016

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
Copy link
Contributor

@jasnell
Copy link
Member Author

jasnell commented May 1, 2016

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
Copy link
Contributor

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

@jasnell
Copy link
Member Author

jasnell commented May 1, 2016

@thealphanerd ... fixed!

@MylesBorins
Copy link
Contributor

MylesBorins commented May 1, 2016

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
Copy link
Member Author

jasnell commented May 1, 2016

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
Copy link
Contributor

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

@jasnell
Copy link
Member Author

jasnell commented May 1, 2016

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
Copy link
Contributor

Fishrock123 commented May 2, 2016

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
Copy link
Member Author

jasnell commented May 2, 2016

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.

</tr>
</table>

* Other Versions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member Author

@jasnell jasnell May 3, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@MylesBorins
Copy link
Contributor

MylesBorins commented May 3, 2016

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
Copy link
Member Author

jasnell commented May 3, 2016

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

@MylesBorins
Copy link
Contributor

no probremo 😄

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

jasnell commented May 4, 2016

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 jasnell force-pushed the changelog-partition branch 3 times, most recently from b588923 to 1489521 Compare May 9, 2016 16:46
@jasnell jasnell removed the wip Issues and PRs that are still a work in progress. label May 9, 2016
@jasnell
Copy link
Member Author

jasnell commented May 9, 2016

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

@eljefedelrodeodeljefe
Copy link
Contributor

LGTM

@MylesBorins
Copy link
Contributor

@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
Copy link
Member Author

jasnell commented May 9, 2016

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

@jasnell
Copy link
Member Author

jasnell commented May 10, 2016

@rvagg ... done.

@jasnell
Copy link
Member Author

jasnell commented May 11, 2016

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

@rvagg
Copy link
Member

rvagg commented May 11, 2016

lgtm

@Fishrock123
Copy link
Contributor

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
Copy link
Member Author

jasnell commented May 11, 2016

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

@jasnell
Copy link
Member Author

jasnell commented May 11, 2016

Notes added to releases.md

@Fishrock123
Copy link
Contributor

LGTM

jasnell added a commit that referenced this pull request May 11, 2016
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>
jasnell added a commit that referenced this pull request May 11, 2016
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
Copy link
Member Author

jasnell commented May 11, 2016

Landed in c663a6d and 118162e

@jasnell
Copy link
Member Author

jasnell commented May 11, 2016

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

@rvagg
Copy link
Member

rvagg commented May 12, 2016

@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
Copy link
Member

lpinca commented May 12, 2016

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

@lpinca
Copy link
Member

lpinca commented May 12, 2016

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.

evanlucas pushed a commit that referenced this pull request May 17, 2016
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>
evanlucas pushed a commit that referenced this pull request May 17, 2016
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
Copy link
Contributor

@jasnell do we still want to backport this?

@jasnell
Copy link
Member Author

jasnell commented Oct 10, 2016

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. meta Issues and PRs related to the general management of the project.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants