added "Next release" header w/ changes + links

[rsek]

the idea is that "Next release" can be updated as changes are made and cease to be "in progress", and then renamed to the next release number when a release is rolled.

[ben]

I see the intent behind this, and it's a good one; "in progress" is a bad name for what this represents. But it's integrated with tooling, which works like this:

• Every PR that does something that the changelog should call out adds a line to the "in progress" section.
• When that PR merges, the change to that section gets merged as well, so the main branch's "in progress" section contains a list of all the stuff that's done, but hasn't been released yet.
• When I'm ready to roll a release, I do npm run bump:minor or some variant. That runs this script, which bumps the version number in system.json and moves all the "in progress" items to underneath a "vX.XX.XXX" header.

I'm happy to consider a new method, but I have a few questions about how it would work. When would I update the "in progress" section? When would I update the "next release" section? What do they signify to the reader (who is probably here because they followed a link from Foundry's "update system" UI)? How does this change the tooling?

[rsek]

aha, that clarifies it a bit. i missed some of the tooling, but i did note the "In progress" header becoming the next dated release header.

but as i looked at the content itself, the purpose of the "in progress" label seemed ambiguous to me. as it stands currently:

In progress

• Code reorganization and format normalization
• Update to the right version of the Foundry types
• Fix the dev server for fewer errors, and so that HMR works

the 1st item is an ongoing, incomplete task (with multiple constituent sub-tasks), requiring weeks (at least) to complete; there's a good chance a release will be made between now and then. my inference: "in progress" = "things that are currently 'in progress' from both a dev PoV and a user PoV"

the 2nd and 3rd items more-or-less directly correspond to work already merged in specific PRs. my inference: "in progress" = "things that are complete from a dev PoV, but still 'in progress' from a user PoV because they aren't released yet"

that led me to the following conclusion:

• the ideal changelog format for a project where a release might be rolled at any time is one where the changelog -- like the code -- is incrementally updated and "ready to ship" at any given point
• if the above isn't practical, then any "intermediate" or "placeholder" items ought to be clearly marked as such, to make it harder to overlook them when rolling a release... and to make it clear that they're intentional placeholders to folks who didn't write them, rather than things that are supposed to be included in the final release changelog entry.

this might be accomplished in a way that's user-facing (e.g. these items are gathered under their own header) or not (e.g. these items have a markdown comment noting this). at the time it made sense to me to go with the former.

however now that i'm not overthinking this at 1am -- maybe it'd be better to automatically generate a changelog from resolved git issues. since, ideally, those are roughly the same thing, yeah? then it's not even something that anyone has to think about beyond "this issue should have a title that's readily understandable" and "this PR should have an issue detailing what it's addressing", which seem like good practices anyways.

[rsek]

and, yes, that won't help much with the individual component PRs i've done already since those are tracked by a single meta-issue 😅 but i can log some for those after the fact for documentation purposes.

[ben]

Closing this specific thing, but I've renamed the "In Progress" area to "Next Release" so it's more clear.