{"action":"created","issue":{"url":"https://api.github.com/repos/nodejs/node/issues/6503","repository_url":"https://api.github.com/repos/nodejs/node","labels_url":"https://api.github.com/repos/nodejs/node/issues/6503/labels{/name}","comments_url":"https://api.github.com/repos/nodejs/node/issues/6503/comments","events_url":"https://api.github.com/repos/nodejs/node/issues/6503/events","html_url":"https://github.com/nodejs/node/pull/6503","id":152206702,"number":6503,"title":"doc: refactor the changelog by version","user":{"login":"jasnell","id":439929,"avatar_url":"https://avatars.githubusercontent.com/u/439929?v=3","gravatar_id":"","url":"https://api.github.com/users/jasnell","html_url":"https://github.com/jasnell","followers_url":"https://api.github.com/users/jasnell/followers","following_url":"https://api.github.com/users/jasnell/following{/other_user}","gists_url":"https://api.github.com/users/jasnell/gists{/gist_id}","starred_url":"https://api.github.com/users/jasnell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jasnell/subscriptions","organizations_url":"https://api.github.com/users/jasnell/orgs","repos_url":"https://api.github.com/users/jasnell/repos","events_url":"https://api.github.com/users/jasnell/events{/privacy}","received_events_url":"https://api.github.com/users/jasnell/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/nodejs/node/labels/doc","name":"doc","color":"006b75"},{"url":"https://api.github.com/repos/nodejs/node/labels/meta","name":"meta","color":"fef2c0"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":25,"created_at":"2016-05-01T15:14:50Z","updated_at":"2016-05-09T20:09:16Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/nodejs/node/pulls/6503","html_url":"https://github.com/nodejs/node/pull/6503","diff_url":"https://github.com/nodejs/node/pull/6503.diff","patch_url":"https://github.com/nodejs/node/pull/6503.patch"},"body":"##### Checklist\r\n\r\n- [x] documentation is changed or added\r\n\r\n##### Affected core subsystem(s)\r\n\r\ndoc (changelog)\r\n\r\n##### Description of change\r\n\r\n/cc @nodejs/documentation @nodejs/ctc @TheAlphaNerd \r\n\r\nThis 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.\r\n\r\nTo see how the proposed change would look in practice, visit: https://github.com/jasnell/node/blob/changelog-partition/CHANGELOG.md\r\n\r\nThis PR reorganizes the changelog by release stream, and brings the following benefits:\r\n\r\n1. 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.\r\n\r\n2. Changelog files include an index / table of contents at the top to easily jump to a specific version.\r\n\r\n3. The root changelog file includes an index of the currently supported release lines for easy navigation.\r\n\r\n4. 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)\r\n\r\n5. 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`\r\n\r\n6. Backporting this to the stable branches ought to be trivial.\r\n\r\n7. It's visible in Github.\r\n\r\nThe downsides of this change are:\r\n\r\n1. 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.\r\n\r\n2. Some of the existing tooling for generating release blog posts (and likely others) will need to be updated to understand this new structure.\r\n\r\n3. 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."},"comment":{"url":"https://api.github.com/repos/nodejs/node/issues/comments/217974503","html_url":"https://github.com/nodejs/node/pull/6503#issuecomment-217974503","issue_url":"https://api.github.com/repos/nodejs/node/issues/6503","id":217974503,"user":{"login":"Fishrock123","id":1093990,"avatar_url":"https://avatars.githubusercontent.com/u/1093990?v=3","gravatar_id":"","url":"https://api.github.com/users/Fishrock123","html_url":"https://github.com/Fishrock123","followers_url":"https://api.github.com/users/Fishrock123/followers","following_url":"https://api.github.com/users/Fishrock123/following{/other_user}","gists_url":"https://api.github.com/users/Fishrock123/gists{/gist_id}","starred_url":"https://api.github.com/users/Fishrock123/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Fishrock123/subscriptions","organizations_url":"https://api.github.com/users/Fishrock123/orgs","repos_url":"https://api.github.com/users/Fishrock123/repos","events_url":"https://api.github.com/users/Fishrock123/events{/privacy}","received_events_url":"https://api.github.com/users/Fishrock123/received_events","type":"User","site_admin":false},"created_at":"2016-05-09T20:09:15Z","updated_at":"2016-05-09T20:09:15Z","body":"@jasnell Right, I know that. But if we really wanted to reduce them (you seemed to like that idea?) we could probably get away with no longer linking a lot of the \"archived\" versions."}}