Versioning and Release Workflow

Deciding what to include in a changeset

When you modify a package, consider not only the package itself but also any dependent packages that need updated versions.

flowchart TD
    utils["@tonic-ui/utils"]
    styled-system["@tonic-ui/styled-system"]
    react["@tonic-ui/react"]
    react-base["@tonic-ui/react-base"]
    react-hooks["@tonic-ui/react-hooks"]
    react-icons["@tonic-ui/react-icons"]
    theme["@tonic-ui/theme"]

    styled-system -.-> utils
    react -.-> styled-system
    react -.-> utils
    react -.-> react-base
    react -.-> react-hooks
    react -.-> react-icons
    react -.-> theme
    react-base -.-> styled-system
    react-hooks -.-> utils
    react-icons -.-> react-base

Loading

For example, if you add new functionality or enhancements to @tonic-ui/utils that are used by @tonic-ui/styled-system, @tonic-ui/react, and @tonic-ui/react-base, you should also bump the versions of those dependent packages — even if no direct code changes were made to them. This ensures that their dependencies are correctly updated and released.

General Rule

• imports from indicates that the change directly affects the descendant package.
• depends on indicates that the change does not directly impact the descendant package.
• Any package that is a descendant via imports from should be updated when the source package changes.

Examples

1. Adding a new utility function in @tonic-ui/utils

flowchart TD
    utils["**@tonic-ui/utils**<br/>minor"]
    styled-system["**@tonic-ui/styled-system**<br/>patch"]
    react["**@tonic-ui/react**<br/>patch"]
    react-base["**@tonic-ui/react-base**<br/>patch"]
    react-hooks["@tonic-ui/react-hooks<br/>no change"]
    react-icons["**@tonic-ui/react-icons**<br/>patch"]

    styled-system -->|✅ imports from| utils
    react -.->|⛓️‍💥 depends on| utils
    react -.->|🔗 depends on| styled-system
    react -.->|🔗 depends on| react-base
    react -.->|⛓️‍💥 depends on| react-hooks
    react -.->|🔗 depends on| react-icons
    react-base -.->|🔗 depends on| styled-system
    react-hooks -.->|⛓️‍💥 depends on| utils
    react-icons -.->|🔗 depends on| react-base

Loading

---
"@tonic-ui/react": patch
"@tonic-ui/react-base": patch
"@tonic-ui/react-icons": patch
"@tonic-ui/styled-system": patch
"@tonic-ui/utils": minor
---

feat(utils): add a lodash-compatible `get` function

• @tonic-ui/utils gets a minor bump for the new feature.
• Dependent packages receive patch bumps to incorporate the updated version.
• @tonic-ui/react and @tonic-ui/react-base were not changed directly, but they rely on @tonic-ui/styled-system, which depends on @tonic-ui/utils.
• Other packages remain unaffected, as they do not use the new utility function.

2. Fixing a bug in @tonic-ui/utils

flowchart TD
    utils["**@tonic-ui/utils**<br/>patch"]
    styled-system["**@tonic-ui/styled-system**<br/>patch"]
    react["**@tonic-ui/react**<br/>patch"]
    react-base["**@tonic-ui/react-base**<br/>patch"]
    react-hooks["@tonic-ui/react-hooks<br/>no change"]
    react-icons["**@tonic-ui/react-icons**<br/>patch"]

    styled-system -->|✅ imports from| utils
    react -->|✅ imports from| utils
    react -.->|🔗 depends on| styled-system
    react -.->|🔗 depends on| react-base
    react -.->|⛓️‍💥 depends on| react-hooks
    react -.->|🔗 depends on| react-icons
    react-base -.->|🔗 depends on| styled-system
    react-hooks -.->|⛓️‍💥 depends on| utils
    react-icons -.->|🔗 depends on| react-base

Loading

---
"@tonic-ui/react": patch
"@tonic-ui/react-base": patch
"@tonic-ui/react-icons": patch
"@tonic-ui/styled-system": patch
"@tonic-ui/utils": patch
---

fix(utils): correct behavior of `merge` function

• @tonic-ui/utils receives a patch for the bug fix.
• Dependent packages receive patch bumps to include the fixed version.
• Other packages remain unaffected, as they do not rely on the merge function.

Version packages

The versioning workflow is automatically handled by the changesets-release action.

If you need to version packages manually, follow these steps:

1. Run yarn changeset version to generate changelogs and update package versions. The release branch will be named changeset-release/{target_branch}.

   # Switch to the main branch and pull the latest changes
   git checkout main
   git pull origin main
   
   # Generate changelogs and bump package versions (review changes before proceeding)
   yarn changeset version
   
   # Update dependencies and regenerate yarn.lock
   yarn
   
   # Create a new release branch
   git checkout -b changeset-release/main
   
   # Stage all changes and commit
   git add .
   git commit -m 'chore(release): version packages'
   
   # Push the release branch to the remote
   git push origin changeset-release/main

2. Open a pull request: chore(release): version packages

3. To update the existing release PR with new changes, run the first step and force-push the updated changes to the same branch.

Release packages

To release packages, approve and merge the version packages pull request. Once merged, packages will be automatically published after a successful build.

To manually trigger a release, navigate to the Actions tab and select the ci-publish workflow. From the Run workflow dropdown, choose the default branch and click Run workflow to start the release process.