react-test/scripts/README.md

Scripts

Release

Prerequisites

1. Make sure you have added the material-ui-docs and upstream remotes to deploy the documentation:

   git remote add upstream https://github.com/mui/material-ui.git
   git remote add material-ui-docs https://github.com/mui/material-ui-docs.git
   

2. Generate a GitHub Token at https://github.com/settings/personal-access-tokens/new and add it to your shell rc script (either .bashrc or .zshrc) as GITHUB_TOKEN.

Releasing a minor version

A minor release goes like this:

Prepare

The following steps must be proposed as a pull request.

1. Generate the changelog with pnpm release:changelog The output must be prepended to the top level CHANGELOG.md pnpm release:changelog --help for more information. If your GitHub token is not in your env, pass it as --githubToken <my-token> to the above command.

2. Clean the generated changelog:

   1. Match the format of https://github.com/mui/material-ui/releases.
   2. Change the packages names casing to be lowercase if applicable

3. Update the root /package.json's version

4. Run pnpm release:version. Keep in mind:

   1. Only packages that have changes since the last release should have their version bumped.
   2. If they have changes, packages that follow Material-UI's versioning scheme should be bumped to the same version as the root package.json. This might require skipping some version numbers.

5. Open PR with changes and wait for review and green CI.

6. Merge PR once CI is green and it has been approved.

Release

1. Go to the publish action.

2. Choose "Run workflow" dropdown

   • Branch: master
   • Commit SHA to release from: the commit that contains the merged release on master. This commit is linked to the GitHub release.
   • Run in dry-run mode: Used for debugging.
   • Create GitHub release: Keep selected if you want a GitHub release to be automatically created from the changelog.
   • npm dist tag to publish to Use to publish legacy or canary versions.

3. Click "Run workflow"

4. Refresh the page to see the newly created workflow, and click it.

5. The next screen will say "@username requested your review to deploy to npm-publish", click "Review deployments" and authorize your workflow run. Never approve workflow runs you didn't initiaite.

Documentation

pnpm docs:deploy to deploy the documentation (it lives at https://material-ui.netlify.app/) with the latest changes. Force push if necessary.

Publish GitHub release

After the documentation deployment is done, review the draft release that was created, then publish it. At this point the release tag gets created. GitHub releases page

Announce

After the docs is live, follow the instructions in https://mui-org.notion.site/Releases-7490ef9581b4447ebdbf86b13164272d.

Releasing a hotfix version

A hotfix release could happen if there is a regression fix that could not wait for the monthly release cycle and the master branch already contains not yet to be released commits. If you can publish an earlier minor or patch, just prefer that over a hotfix release.

It goes like this:

Prepare

Hotfix branch creation requires the help of a repository admin. They need to take the following steps:

1. Check out the commit for the latest release tag.

2. Create a branch named release/<PATCH_VERSION> where <PATCH_VERSION> is the next semver patch version from that release tag.

3. force push the branch to upstream:

   git push -f upstream release/<PATCH_VERSION>
   

The following steps must be proposed as a pull request to release/<PATCH_VERSION>.

1. check out release/<PATCH_VERSION> and cherry-pick the hotfix commits on top of it.
2. Generate the changelog with pnpm release:changelog The output must be prepended to the top level CHANGELOG.md pnpm release:changelog --help for more information. If your GitHub token is not in your env, pass it as --githubToken <my-token> to the above command.
3. Clean the generated changelog:
   1. Match the format of https://github.com/mui/material-ui/releases.
   2. Change the packages names casing to be lowercase if applicable
4. Update the root /package.json's version
5. Run pnpm release:version. Keep in mind:
   1. Only packages that have changes since the last release should have their version bumped.
   2. If they have changes, packages that follow Material-UI's versioning scheme should be bumped to the same version as the root package.json. This might require skipping some version numbers.
6. Open PR with changes and wait for review and green CI.
7. Merge PR into release/<PATCH_VERSION> once CI is green and it has been approved.
8. Open and merge a PR from release/<PATCH_VERSION> to master to correct the package versioning and update the changelog.

Release the packages

1. Run pnpm release:publish. You may be asked to authenticate with GitHub when running the command for the first time or after a very long time.

2. It'll automatically fetch the latest merged release PR and ask for confirmation before publishing.

3. If you already know the sha of the commit, you can pass it directly like pnpm release:publish --sha <your-sha>.

4. Other flags for the command:

   • --dry-run Used for debugging. Or directly run pnpm release:publish:dry-run.
   • --dist-tag Use to publish legacy or canary versions.

5. This command invokes the Publish GitHub action. It'll log the url which can be opened to see the latest workflow run.

6. The next screen shows "@username requested your review to deploy to npm-publish", click "Review deployments" and authorize your workflow run. Never approve workflow runs you didn't initiaite.

Documentation

Run git push -f material-ui-docs HEAD:latest to deploy the documentation (it lives at https://material-ui.netlify.app/) with the latest changes. Force push if necessary.

Publish GitHub release

After the documentation deployment is done, review and then publish the release that was created in draft mode during the release step GitHub releases page

Cleanup

After the release is done, merge the branch back to master. While merging make sure to resolve conflicts considering master may have future changes done in the same files.

Announce

After the docs is live, follow the instructions in https://mui-org.notion.site/Releases-7490ef9581b4447ebdbf86b13164272d.

Deploy documentation without a release

Sometimes it is necessary to deploy the selected commit(s) without deploying all the changes that have been merged into the main branch since the previous release (for example publishing a blog post or releasing urgent docs updates).

Note: The instructions below are for deploying to the latest branch of the material-ui-docs repository, which points to https://mui.com/. If you need to deploy to a different subdomain, replace latest with the appropriate branch name:

• latest: https://mui.com/
• next: https://next.mui.com/
• v*.x: https://v*.mui.com/

To do so, follow these steps:

1. Add the material-ui-docs remote if you haven't done this already:

   git remote add material-ui-docs https://github.com/mui/material-ui-docs.git
   

2. Fetch the latest changes from the material-ui-docs remote:

   git fetch material-ui-docs latest
   

3. Switch to the latest branch from material-ui-docs remote:

   git switch --detach material-ui-docs/latest
   

4. Cherry-pick the commit(s) that you want to include in the new deployment:

   git cherry-pick <commit>
   

   It will commit the changes if there are no conflicts.

   In case of conflicts you will need to resolve them and commit the changes manually.

   If this command fails with the message 'bad revision', it means that the commit doesn't exist on your local repository. The commit might have been created on a remote branch, probably when merging into master or v*.x. In this case, you'll have to fetch the latest changes of the corresponding remote branch and then try again.

5. Push the changes to the material-ui-docs remote:

   git push material-ui-docs HEAD:latest
   

6. Switch from detached HEAD back to your last checked out branch:

   git checkout -