release plan helper command

[romainmenke]

Context :

We have a whole lot of packages and now that we are also authoring our own tokenizers and parsers the dependency graph can easily become complex.

Publishing everything is a lot of work when you have to get these things right consistently :

• correct version increment
• correct CHANGELOG.md edit
• correct publish order
• what to publish
• ...

---

What if we use the CHANGELOG.md as a signal to create and execute a release plan.

Each CHANGELOG.md for an unreleased update has : Unreleased (patch|minor|major).
Anything else is ignored.

When publishing you first run : npm run release-plan --dry-run.
This will tell you :

• what will be released
• in what order
• the increment

Release plan:
  - @csstools/css-tokenizer (patch)
  - @csstools/selector-specificity (patch)
  - @csstools/postcss-progressive-custom-properties (patch)
  - css-blank-pseudo (patch)
  - ...

When publishing for real you run : npm run release-plan.

---

How it works :

• list all workspaces
• build a dependency graph
• check the CHANGELOG.md file for each
• create a list of only those packages that have up to date local dependencies
• increment the version
• re-generate docs
• publish
• commit the version increment

The publish sub process inherits stdio from the main process.
So a prompt for 2FA will just be passed to you.

After all releases :

• increment the versions of freshly released dependencies in other packages
• run npm install to update the lock file

These changes are not committed to make it easier to review what has changes.

"up to date local dependencies" means that this package does not depend on another local package that needs to be released

---

Thoughts?

[Antonio-Laguna]

I'd say let's give it a spin!

THANKS for adding this :)

I think it's missing the docs --if-exist part for packages that have version number but other than that is looking solid!

[romainmenke]

I want to take it slow and try it one by one first.
So the script will stop after a single package.

If that works you can simply remove these lines and it will do the whole batch.

[romainmenke]

forgot to mention explicitly

Because packages with unreleased local dependencies are skipped you will need to run it multiple times. In theory I can let it bump dependency versions and continue from there.

But I think it is better if it only releases things that were prepared by a human and doesn't start to alter and release packages on it's own.

for example :

1. release an update for @csstools/css-tokenizer
2. go to @csstools/css-parser-algorithms
3. bump the version for dependency @csstools/css-tokenizer
4. release an update for @csstools/css-parser-algorithms

I can make it capable of this.
But it feels a bit too magical at this time :D

The downside is that we will still need to alter a few things manually in between chunks of releases.

It now stops at 3. So it will bump the version of dependencies after each release chunk.
But it won't even commit that.

---

There are two error cases I am a bit worried about in this context :

1. the script has a bug and suddenly we have released a broken state of everything
2. someone prepared a release for a package but didn't consider a downstream change

1 : Over time we will find out if the script is dependable or not. If we are confident it is good we can make it do more. There is also not much difference between releasing 5 or 50 broken states. It will require cleanup either way.

2 : I think this will be extremely rare.