How we need to do Changesets going forward

[SiTaggart]

Problems

Major version bumps for peer dependencies

Changesets currently bump all peer dependencies as major version bumps. This might mean that:

• a minor version bump of Button will cause a MAJOR version bump of Alert, Combobox, Menu, Modal, Popover and Toast.
• a minor version bump of Icons will cause a MAJOR version bump of Core

Icons minor = MAJOR ALL THE THINGS

This makes our versioning not super clear on severity and likely mean we ramp up major versions of our packages very quickly. We'll be a @twilio-paste/core@27.0.0 before we know it.

Peer dependency versioning cascade

When we bump a peer dependency, this can create a cascade of package releases down the dependency tree. These releases are merely to bump a version number.

This creates a whole bunch of noise of meaningless version updates and changelogs that are verbose and hard to read.

Icons minor = version bump all the things

Core package changelog details

Up until now the Core package changelog includes no details about what actually happened in the dependency that got bumped. If something happens in Button, I need to go and look in button to find out what will be included, rather than just read it from the Core changelog.

Similarly for BREAKING CHANGES. None are listed in the Core changelog, they only appear in the downstream package changelog and that is potentially misleading.

As an example this changelog tells me nothing of what actually happened to core

onlyUpdatePeerDependentsWhenOutOfRange doesn't actually work with pinned dependencies

Because our inter dependencies are pinned, and update to any package is always out of range. So every package always gets updated. This flag, literally does nothing for us right now.

You only see benefits when you version inter dependencies with a ^ minor range.

Whats changing?

Internal dependency version ranges

Packages will once again have minor ^ ranges. This will mean that a peer dependency update will only get triggered with MAJOR version bumps to the parent package.

- "@twilio-paste/button": "1.5.0"
+ "@twilio-paste/button": "^1.5.0"

• This means a minor version bump of Button will only cause a version bump in Core.
• No Version bump cascade, significantly reducing package releases.

Core tied to every package changeset

Each change to a package must also apply to the Core package. This will mirror the level of version bump across the package and Core. It also overrides the Major version bumps for peer dependencies behaviour of Changesets

---
'@twilio-paste/button': minor
'@twilio-paste/core': minor
---

Details about some change to button

• A Patch version bump of Button, will be a Patch version bump in Core.
• A Minor version bump of Button, will be a Minor version bump in Core.
• A Major version bump of Button, will be a Major version bump in Alert, Combobox, Menu, Modal, Popover, Toast and Core.
• A Patch version bump of Icons, will be a Patch version bump in Core.
• A minor version bump of Icons, will be a Minor version bump in Core even though the default would be a MAJOR core releases as Icon is a peer dep
• A Major version bump of Icons, will be a Major version bump in Core and all Icon dependents.

Clearer, more relevant Changelogs for Core

Each changeset being linked to Core will include the package changeset into the Core changeset for a more clearer Core Changelog of whats actually included

Each changeset being linked to Core and reduced package releases means that the Core Changelog no longer becomes a list of version bumps. You only see what happened to the downstream package for every release going forward.

Each changeset being linked to Core will still cause the consumer to get all necessary packages changes when they upgrade, without every package needing a version bump

Core bundle automation

Automatically adding and updating the Core package JSON needs to change slightly and be given up to Changesets.

There will be some instances where the package version numbers will be out of sync with the version listed in Core as Changesets will not bump a version that is with in range of the minor ^

• e.g. V1.6.2 will be satisfied by a ^1.4.0

Continuing to update update the core package JSON file in the way we currently do with build, will mean git out of sync issues every release, so we'll need to tweak the way we generate the packages, preserve the existing version numbers and only add new packages to the list.

[loreina]

Closing due to inactivity.