VERSIONING.md

author
Mark Chandler

Versioning Strategy

Since @chakra-ui/react acts as a combined gateway to (nearly) all Chakra UI functionality, its version should reflect that by having all minor version bumps to its internal dependencies applied to itself as well. This allows the @chakra-ui/react package to reflect all backwards-compatible functionality changes for the system as a whole.

We've currently configured https://github.com/atlassian/changesets to bump internal dependency changes using patch which is probably the more correct thing to do in that situation since the technically correct thing would result in constant major version bumps, but in the case of @chakra-ui/react, we want to instead receive any minor version bumps.

Examples

In my mind, here's how versioning should look (assume all packages starting at 1.0.0):

1. Internal dependency adds backwards-compatible functionality

• @chakra-ui/hooks adds a new useCoolThing export
  • @chakra-ui/[email protected] -> @chakra-ui/[email protected] (minor)
• @chakra-ui/[email protected] -> @chakra-ui/[email protected] (minor) to reflect the added system-level functionality

2. Multiple internal dependencies add backwards-compatible functionality

• @chakra-ui/hooks adds a new useCoolThing export
  • @chakra-ui/[email protected] -> @chakra-ui/[email protected] (minor)
• @chakra-ui/accordion adds a new AccordionCoolestItem export
  • @chakra-ui/[email protected] -> @chakra-ui/[email protected] (minor)
• @chakra-ui/[email protected] -> @chakra-ui/[email protected] (minor) to reflect the added system-level functionality

3. Internal dependency adds bug fix

• @chakra-ui/hooks fixes a bug with useCoolThing
  • @chakra-ui/[email protected] -> @chakra-ui/[email protected] (patch)
• @chakra-ui/[email protected] -> @chakra-ui/[email protected] (patch) to reflect the system-level bug fix

4. Multiple internal dependencies add bug fixes

• @chakra-ui/hooks fixes a bug with useCoolThing
  • @chakra-ui/[email protected] -> @chakra-ui/[email protected] (patch)
• @chakra-ui/accordion fixes a bug with useAccordionItem
  • @chakra-ui/[email protected] -> @chakra-ui/[email protected] (patch)
• @chakra-ui/[email protected] -> @chakra-ui/[email protected] (patch) to reflect the system-level bug fixes

5. Internal dependencies add backwards-compatible functionality and bug fixes

• @chakra-ui/hooks fixes a bug with useCoolThing
  • @chakra-ui/[email protected] -> @chakra-ui/[email protected] (patch)
• @chakra-ui/accordion adds a new AccordionCoolestItem export
  • @chakra-ui/[email protected] -> @chakra-ui/[email protected] (minor)
• @chakra-ui/[email protected] -> @chakra-ui/[email protected] (minor and patch) to reflect maximum version bump of all system-level changes (I believe this is the automatic changesets behavior, but I need to test that; see https://github.com/atlassian/changesets/blob/master/docs/decisions.md#how-changesets-are-combined for more info)

6. New package is published

• @chakra-ui/new-component is created
  • @chakra-ui/[email protected] to reflect start of new package
• @chakra-ui/[email protected] -> @chakra-ui/[email protected] (minor) to reflect the added system-level functionality

How?

I think we have two possible solutions:

• Include @chakra-ui/react in all changeset files matching the version bump of the dependent package. This requires manual effort, but allows us to fully control the process.
• Build our own customized release plan. I'm not sure changesets supports this yet and need to investigate, but it would allow us to automate this so we don't have to always include @chakra-ui/react bumps in our changeset files.