These instructions describe how to cut a new release.
MDC follows the "git flow" style of
development, where the default branch is called develop. stable (instead of the traditional
master) is reserved for releases. The develop branch is periodically copied to a release candidate,
tested, and then merged into stable, which serves as the stable "vetted" branch.
Each release is driven by a single release engineer, who is also a Googler. The release engineer is expected to do the following, in order of priority:
- Do not break Google.
- Cut a release by first thing Wednesday morning, NYC time, without exception.
- Land a release at least once a week.
If something is stopping the release engineer from achieving any of the above goals, the culprit code should be removed immediately from the release.
Importantly: do not block the cutting of the weekly release on a PR or a piece of functionality you'd like to land. If your PR hasn't landed by the time the release is cut, it's not making it into that week's release. If your PR is important, cut a hotfix release in addition to the typical weekly release.
If you are not able to cut a release Wednesday morning, cut it Tuesday evening before you leave the office.
For Googlers, also read go/mdc-release-engineering for additional details.
Make sure you are working from a direct clone of the main Git repository. The scripts involved assume that the remote "origin" is the actual repository and not your fork. Since most contributors will be working day-to-day with a fork, consider creating a separate clone just for releases.
git clone [email protected]:material-components/material-components-ios.git mdc-ios-release
cd mdc-ios-release
Our entire release process is encoded into the release script in the scripts/ directory.
Read the tool's readme to learn more about the tool.
Run the following command to cut a release:
scripts/release cut
Note: if for some reason cut fails, first ensure that nobody else is in the middle of cutting a release by visiting the repo and verifying that a release-candidate does not already exist because aborting the release will delete the remote release candidate. If that isn't the case, then please run scripts/release abort and try again.
You will now have a local release-candidate branch, a new section in CHANGELOG.md titled
"release-candidate", and the release-candidate branch will have been pushed to GitHub.
At this point you should also create the initial Release Candidate pull request using the URL
that the cut script generated.
Name the Pull Request title "[WIP] Release Candidate." until you are able to provide the version as the title.
Add "@Release-blocking clients" to the pull request's reviewers. This is the mechanism by which release-blocking clients are notified of a new release.
Do not use GitHub's big green button to merge the approved pull request. Release are an exception to our normal squash-and-merge procedure.
If you need to cut a hotfix release, run the following command instead:
scripts/release cut --hotfix
A hotfix release is like a regular release, but its scope is limited specifically to the fix. Hotfix release candidates start from origin/stable rather than origin/develop.
If the hotfix is to fix a regression or a problematic commit in a recent release, the ideal
path forward is to revert that commit using the git revert <commit-hash> command and opening a PR with that change to the develop branch.
After that PR is merged, you should cherry-pick the revert commit into the release-candidate branch: git cherry-pick <commit-hash>.
Other than the steps above regarding hotfixing, the entire release process stays the same.
You can now start the internal release testing process documented at go/mdc-releasing.
Push release-candidate to GitHub with git push origin release-candidate as you make changes.
This allows other people and machines to track the progress of the release.
You, or clients, may find problems with the release that need fixing before continuing. You have two options for making those changes:
- If the change does not touch library code and is trivial, then you can make the change directly on the release candidate branch.
- If the change touches library code, is non-trivial, or you just want a second opinion, create a
pull request targeting
release-candidateand get it reviewed.
Note that in both cases, changes made to the release candidate branch will be merged back into
develop at the end of the release.
The two most important bits of metadata about a release is the new version number and the release notes. While we have tooling to help, your job is to make sure these are correct. If you're not familiar with MDC's version number policy, please review it now.
To figure out the release number you will need to examine the release's changes.
You have several tools available for deciding if a release is major, minor, or a patch.
CHANGELOG.md automatically includes the latest set of public API changes as part of the cut command.
Inspect the API changes to get a quick sense of whether there might be an API-breaking change.
- If any part of a public API is deleted or changed, then this release is a major release.
- If any public API's nullability annotations have changed then this release is a major release.
- Otherwise, if any public APIs added, then this release is a minor release.
- Otherwise, this release might still be a bug fix release.
In the "New Features" sub-category generated by the API diff tool, please provide more detail as to what is new in the release, also providing examples on how to use the added public API properties/methods. For instance if you have added the method setShadowWidth: to MDCCard an example usage would be:
let card = MDCCard()
card.setShadowWidth(10)In the top level description please provide a sentence explaining the overall release. Something along the lines of: "This minor/major/patch release includes X and Y along with some Z."
While we do primarily lean on the api_diff tool to call out API diffs, it isn't perfect. For each API change, open the source at the latest checkout and verify that the API change does, in fact, reflect the change that occurred.
Adjust the API diffs in CHANGELOG.md based on your visual inspection of the code.
Commit the final results to your branch.
git add CHANGELOG.md
git commit -m "Hand-modified CHANGELOG.md API diff."
git push origin release-candidate
We do not presently have an automated way to identify visual changes between releases. See GitHub issue #290 for a discussion on the topic.
The final sanity check is to visually inspect the diff.
If you have configured Git with a GUI diff tool (
git difftool) like Kaleidoscope, then you can add--use_diff_tooltoscripts/release diffbelow.
Generate a list of component public header changes:
scripts/release headers
Show changes to component headers:
scripts/release diff components/*/src/*.h
Show all changes to components:
scripts/release diff components/*/src/
Show all changes that are part of this release:
scripts/release diff
You should now be able to identify the release type and its new version number. Bump the release (change the version number everywhere):
scripts/release bump <major.minor.patch>
Commit the results to your branch:
git commit -am "Bumped version number to $(scripts/print_version)."
git push origin release-candidate
Send our local podspec through the CocoaPods linter:
pod lib lint MaterialComponents.podspec --skip-tests
CocoaPods publishes a directory of publicly available pods through its trunk service.
Note: Ensure that you can push the podspec later by checking for MaterialComponents in your list of available Pods when you:
pod trunk me
If this fails or MaterialComponents is not listed register an account and session.
Before you can merge the release branch into either develop or stable you must get the release go-ahead from the following clients:
- Google: must verify that the release branch passes all internal tests. If you are a Googler, see the internal "mirroring" document for further instructions. Notably you must not continue this releasing process until the internal synchronization CL has been tested.
|\___/|
(,\ /,)\
/ / \ DRAGON SAYS HALT:
(@_^_@)/ \ READ THE ABOVE SECTION BEFORE CONTINUING.
W//W_/ \ DO NOT MERGE OR CUT ANY RELEASES UNTIL
(//) | \ YOU'VE DONE SO.
(/ /) _|_ / ) \
(// /) '/,_ _ _/ (~^-.
(( // )) ,-{ _ `.
(( /// )) '/\ / \
(( ///)) `. { } \
((/ )) .----~-.\ \-' ~-__
///.----..> \ \_ ~--____
///-._ _ _ _} ~--------------
Once the release-candidate has passed all tests by clients, you may merge the release into the
develop and stable branches using the release script.
Do not use GitHub's big green button to merge the approved pull request. Release are an exception to our normal squash-and-merge procedure.
# Did you listen to the dragon?
#
# Do not run this until all release-blocking clients have given the go-ahead.
# Ensure that you've checked off every item in the commit message's checklist.
#
scripts/release merge <version>
Once you've resolved any merge conflicts your local develop and stable branches will both
include the latest changes from release-candidate.
You must merge to both develop and stable. This is the mechanism by which we ensure that stable matches develop.
You can now push the merged release candidate to GitHub so that you can complete the final synchronization within Google.
git push origin stable develop
You can now sync to the desired stable release. go/mdc-releasing#re-run-the-import-script-against-githubstable. Once you've submitted the internal CL, continue below to tag and publish the release.
Have all release-blocking clients given the go-ahead? Do not create the official release until all release-blocking clients are ready. Otherwise you might publish a release that isn't actually stable.
You can now publish the release to GitHub:
scripts/release publish <version>
git checkout stable
pod trunk push MaterialComponents.podspec --skip-tests
Any work that was started by the Release-blocking clients (dragon) step above may need to be finalized.
Also follow last instructions in the internal release instructions