Introduction

When there is a new release for Core products (Material UI, Base UI, Joy UI, Pigment CSS, MUI System), the release process goes on pre-alpha phase, alpha phase, beta phase, and finally, a stable one.

Once the release process is started, a few steps are needed to start delivering the alpha and beta versions of the new major version, for which an infrastructure setup is needed, which will be discussed in this document.

Before starting alpha (branch cut)

For a stable version, the default branch is master, but when the release process is started, the new branch next becomes the default branch, and from that point onwards, only the important bug fixes are ported back to the master branch; all the rest of the new features, enhancements, etc. are merged into the next branch until the stable release is done.

Before starting the alpha, these steps need to be taken on a date mutually decided by the team (examples below will assume the major version being released to be v6):

  1. ✅ Start a new branch next from the current master branch commit.
  2. ✅ Make next the default branch in GitHub https://github.com/mui/material-ui/settings.
  3. ✅ Create branch protection rules for next to match those for master
  4. ✅ Change the target branch of all open PRs from master to next.
  5. ✅ Start migration pages for each set of products (Material UI, MUI System etc) Example: https://github.com/mui/mui-x/pull/6235/files
    1. preferably in a separate PRs
  6. ℹ️ From this point on, until the first alpha release and beyond, these activities should happen:
    1. Keep working on the breaking changes while adding the breaking change label on the PR and closing the respective checklist items in the preparing the release umbrella issue
    2. For each PR with a breaking change: Update the migration guide with a breaking change description and migration instructions (if necessary).
    3. Merge everything by default on next and cherry-pick the bug fixes, localization changes (or other important issues) on the master to be released under the currently active major.
    4. Where relevant, keep adding version-specific labels (e.g., v5.* and v6.*)
    5. Keep releasing when necessary from the master as the currently active major version

First alpha release, during alpha phase, beta release

Before the first alpha release, these steps need to happen:

  1. Netlify docs deployments are made from thenext git branch. So, pushing the current state of the next branch is sufficient to start working on that.

    1. ✅ Change the default release in the version dropdown
    2. ❌ maybe/optional: update the UI of the docs
    3. ✅ add the alpha-release in the master version dropdown

  2. ✅ Update the deploy script in docs/package.json to push to next:next instead of master:latest

  3. ✅ Change the release:publish script to use the next tag

  4. (normally no longer needed) Update Argos CI’ baseline branch to be next , https://app.argos-ci.com/mui/mui-x/settings

    Screenshot 2023-12-26 at 23.16.55.png

  5. ✅ Update the instance of #default-branch-switch in the source. Example: https://github.com/mui/material-ui/pull/41552

  6. Update the examples to use the next tag - https://github.com/mui/material-ui/pull/41701