chore(docs): archive old changelog entries

[rvagg]

CHANGELOG.md is finally too big for GitHub's angry unicorn to render properly.

I'm going pretty hard on this one, archiving everything prior to 1.30.0; grouping them by every 10 versions in semver-minor, and providing a TOC and an index for old versions. Open to suggestions for alternative approaches.

I also wouldn't mind reconsidering out approach to the "unreleased" section because it's the main source of git conflicts when merging, backporting or cherry-picking. I'm thinking that a proposed changelog entry might be better off going in the GitHub PR comment thread somewhere and we can have tooling pick it out. Or; maybe we come up with a convention for how to put it in commit metadata. But maybe we can look at that as a separate item.

Direct links to previews of the edited files:

• https://github.com/filecoin-project/lotus/blob/rvagg/changelog/CHANGELOG.md
• https://github.com/filecoin-project/lotus/blob/rvagg/changelog/documentation/changelog/CHANGELOG_0.x.md
• https://github.com/filecoin-project/lotus/blob/rvagg/changelog/documentation/changelog/CHANGELOG_1.0x.md
• https://github.com/filecoin-project/lotus/blob/rvagg/changelog/documentation/changelog/CHANGELOG_1.1x.md
• https://github.com/filecoin-project/lotus/blob/rvagg/changelog/documentation/changelog/CHANGELOG_1.2x.md
• https://github.com/filecoin-project/lotus/blob/rvagg/changelog/documentation/changelog/README.md

[BigLep]

I like this @rvagg , and I'm wondering about taking it fuurther for 1.30.0+ going forward.

What if we create one changelog file per minor release?

I'd like to get out of the business of duplicating the content between changelog files and the github release. I'm proposing the github release page just have an authoritative link to the changelog for the release. (Why? Prevent duplication, but also because there's not PR process around edits to the release page.)

I think this process is simplified if we have easy-to-construct and deterministic URLs to a given release's changelog. Something like:

https://github.com/filecoin-project/lotus/tree/release/vX.Y/Z/documentation/changelog/CHANGELOG_X.Y.x.md
or
https://github.com/filecoin-project/lotus/tree/release/miner/vX.Y/Z/documentation/changelog/CHANGELOG_X.Y.x.md

https://github.com/filecoin-project/lotus/blob/master/CHANGELOG.md can still house the unreleased work and the links to all the changelog files. Before creating the release branch though we'd create the new documentation/changelog/CHANGELOG_X.Y.x.md file and clear the "unreleased work" section in master/CHANGELOG.md so there should be no conflicts later when when we merge back from the release branch to master.

I'm happy to talk more verbally or write this out better.

Even if we go with some variant of what I'm suggesting, I don't think it blocks shipping what you've done.

Thanks again.

[BigLep]

@rvagg spoke on this more 2024-12-05. Some brief notes:

1. This current PR should definitely ship as is
2. It's nice to have release notes in the release page itself since that is what comes through in GitHub notifications. We get more visibility if users don't have to click to read somewhere else.
3. Merge conflicts on the changelog.md are going to keep happening if we have the same process of usually requiring a changelog update, moving content out of the unreleased section when starting a release, and then bringing it back in at the end of a release.
4. This needs to get thought about more, but maybe we keep changelog content drafting out of the changelog.md file. Instead have a section in the PR description or a special comment where someone (author or reviewer)can either:
   • "skip changelog"
   • "use the commit message" and rely on no extra editorializing (Example where this would have sufficed: feat: add network tag to metrics #12733 )
   • custom editorializing
     There would then be tooling to enforce one of the 3 options above happens (like we have now) and to extract the relevant content for preventing the first draft to the release engineer who will finish it off.
5. The reason why Lotus is having a problem (i.e., why is Lotus special):
   • Other projects resolve to just have good commit messages and let that drive the changelog. Lotus wants editorializing beyond just having good commit messages.
   • Other projects have one person who does the editorializing based on the commit messages. Lotus is trying to avoid having one person do that (especially during the release process time where there can be more time pressure and crunch.)