Changesets and package interdependence

[xander-marjoram]

On my latest PR to update pie-icons, @dandel10n left a comment asking about whether or not the next Version Packages PR would correctly update pie-icons-vue, pie-icons-webc and pie-icons-react, as they all have a devDependency on pie-icons.

Seeing as the generated icons for each of these packages are no longer kept in source control, there were no code changes for any of those packages as far as Git is concerned.

With the help of @siggerzz, we managed to debug the changeset process.

Expand for a step-by-step guide to debugging changeset versioning locally.

1. Create a new github personal access token here. It should have read:user and repo:status permissions. I used a classic token rather than fine-grained.
2. Copy the token value and assign it to the environment variable GITHUB_TOKEN on your console.
3. Make sure there is at least one changeset file in the .changeset folder. Feel free to isolate the effects of a single file by deleting the others (but make sure you don't commit this!).
4. Remove the "changeset" line from .changeset/config.json.
5. Run yarn changeset:version from the root. This will carry out the versioning locally.
6. If you want to re-run it, undo all of the changes that were made by the command (but making sure you haven't undone step 4) before running step 5 again.

From this, we determined that changeset would increment the version of pie-icons (as expected) and update the package.json of the consuming packages to reference this new version (also as expected). However, the versions of the consuming packages themselves would not be incremented. This meant that the publish step failed as the versions listed in the package.json files had already been published before. Example log

There are a different ways around this:

1. Manually add a changeset for pie-icons-webc, pie-icons-vue and pie-icons-react so that changeset would increment their versions. This works perfectly but is prone to human error.
2. As above, but set up some way of reminding contributors to add another changeset if pie-icons has been updated. This would be an improvement but it only captures that particular dependency. What should we do about dependencies between other packages, for example pie-modal depending on pie-icon-button, pie-button, etc.
3. Find another way of making sure a changeset is generated based on a dependency tree, or similar.

We went on to discover that we currently define a number of linked packages in the changeset config.. The documentation for this can be found here but essentially this was not working as intended. (Note that pie-icons-webc was missing.) Also note that just above the examples on that page, it says:

Unlike fixed packages, there is no guarantee that all packages in the group of linked packages will be version-bumped and published, only those with changeset(s) will be.

This is why we needed to add a changeset for pie-icons-vue, pie-icons-webc and pie-icons-react. This also mentions fixed packages, which are described here. We decided against this because there was no reason to keep the versions for the Vue and React icons aligned, for example, because it is unlikely that they will both be consumed at the same time, so there isn't really a benefit of doing so. It would also mean that if we updated the React icons, a new version would be published for pie-icons itself, which could also be confusing.

Additional notes / complications:

• Some packages have workspace:* dependencies on others, so they pull the latest changes from the repo whether they have been published to npm or not.

[fernandofranca]

Double-checking to see if I got it right:
If pie-icons is updated, we should manually bump the changeset for pie-icons-vue, pie-icons-webc, and pie-icons-react?
Do we need to update and release a new package of the other dependents, like pie-modal?

[xander-marjoram]

@fernandofranca You're correct that we need to add a changeset for the -vue, -webc and -react packages whenever we change pie-icons.

Currently, I don't think it's necessary to do the same for pie-modal, for example, because it has a workspace:* dependency on the icons (and other components). If we instead reference specific published versions then this may change.

[ashleynolan]

I personally think that we should fix the icon packages together – it's actually what we thought the link config would do initially, but it isn't working as expected (as you explained really well).

The reason I think fixing is a good idea for the icon packages is because it avoids any confusion for consumers across our icon packages. When referencing icons, if someone is using v1.3.1 of pie-icons-react, we don't have to ask them (or go and find out) what version of pie-icons that uses. For icons, where there are lots of small dependent changes, I think this consistency and clarity benefit outweighs the potential negative of bumping the package when no change has actually occurred (for example, as you say, when pie-icons-vue is updated then pie-icons-react will also get bumped. In practice, as the packages become more stable, it's likely that very little change will go into the vue/react packages unless it's a bigger change which will likely affect both anyway.