📝 Documentation: Batching multiple commits for a single release or triggering a new release after the fact

[ChristianIvicevic]

Documentation Report Checklist

• I have pulled the latest main branch of the repository.
• I have searched for related issues and found none that matched my issue.

Overview

I have scaffolded a new package using your template and got it working for the most part but noticed a few unclear steps in terms of the intended workflow and would like to know how to handle these as I haven't seen sufficient documentation on it.

1. Creating the repository also sets up GitHub in an opinionated way, specifically disabling rebases and forcing everything to be squashed. As such anything that ends up in the main branch will always be a single commit, be it directly to main or via a PR. The release workflow therefore cannot pick up multiple changes at the same time, say two features. This is particularly relevant when I'm preparing a minor or even a major version release and wouldn't want all the separate changes be summarized under a single umbrealla feat entry in the changelog and instead would like my users to actually see in detail what has changed. What's the recommended process to batch these changes for a single release?
2. In a similar fashion certain commits such as dependency updates don't trigger a release since they are prefixed with chore, especially when it's from renovate. What about the case where a critical vulnerability gets updated? This doesn't trigger a release and it seems I'd have to push an empty commit with fix to trigger a release which really doesn't feel right. How am I supposed with the default setup to trigger a release after performing some more relevant dependency updates?

Additional Info

No response

[JoshuaKGoldberg]

Thanks so much for using the template! This is for https://github.com/ChristianIvicevic/intl-watcher, right? It looks great, very nicely done API and documentation 🙂.

For releases in general, I have to admit it's not an area I've put a lot of feature effort around. These are good questions to ask - in order...

What's the recommended process to batch these changes for a single release?

There is none right now. I'd welcome any suggestions you have for making this doable. The current https://github.com/JoshuaKGoldberg/release-it-action flow is optimized for simplicity ("one commit per release") as you've noted, and doesn't have much flexibility beyond that. You might be better served by replacing it with manual steps or something like https://github.com/changesets/changesets.

Are there processes you've used before / can link here that work the way you want?

chore vs. fix

I believe Renovate will mark any user-facing dependencies as fix: renovatebot/renovate#1340. Is that what you're looking for?

If the problem is that changes to some devDependencies can also cause user-facing outputs that should make the PRs fix instead of chore, you might want to customize the Renovate config to mark those specific devDependencies as fix-level.

Just for completeness, you could also disable Renovate auto-merging and manually edit PR titles. Or even remove Renovate altogether. CTA doesn't have a way to remove parts of its templating for an existing repo, so that'd have to be manual - but npx create-typescript-app --exclude-renovate would work for a new repo.

trigger a release after performing some more relevant dependency updates?

I can't think of a good way to trigger a release through GitHub actions that doesn't involve git commit --allow-empty -m "fix/feat: empty commit to trigger CI" 😬. You could publish manually locally, but then you'd lose package provenance. This might be another good motivation for you to switch to something like Changesets?

Related questions that also should be documented somewhere:

• 📝 Documentation: how to release beta versions of a package? #912
• 📝 Documentation: How to bump to a new major version #1671

[ChristianIvicevic]

Are there processes you've used before / can link here that work the way you want?

It has been five years since last I published something to npm so the tooling has changed, but the tool I used was Release Please and it had a release PR open which tracks relevant commits to the main branch, updates the changelog, and updates the package.json etc. As such it was possible to push to the main branch and trigger a release at any time when the release PR was merged. It's likely I'll consider moving to such a workflow again after investigating what tools are more common these days.

I'm a bit terrified of the thought of migrating the tooling for the release workflows after using your release action but I'd rather do it before I release a v1 anyways 😅

[JoshuaKGoldberg]

That sounds good! We use Release Please in Mocha (ref: mochajs/mocha#5186) and it's worked well for us.

Maybe also useful: CTA used to use Semantic Release, but switched to release-it because SR doesn't support 0.x versions (https://semantic-release.gitbook.io/semantic-release/support/faq#can-i-set-the-initial-release-version-of-my-package-to-0.0.1).

In the meantime, marking as accepting PRs to document:

• What's the recommended process to batch these changes for a single release?
• How am I supposed with the default setup to trigger a release after performing some more relevant dependency updates?

...where figuring out the answers to those will need to be done as part of this task.

[ChristianIvicevic]

Small update: after testing it in a separate throwaway repo/package I have decided to migrate to changesets. One tricky thing was the inclusion of changesets for renovate which aren't supported out of the box but I found a promising action that handles this. For anyone interested here's the diff of replacing the release-it flow with changesets: ChristianIvicevic/intl-watcher@9aa3edc