The releasing process is being combined in a Google-internal document to
reduce errors introduced by jumping between the two documents. The current
`releasing.md` is being replaced with general information about the release
process that may be relevant to clients and contributors.
The previous contents of this file have already been imported to Google by
cl/289097261.
Part of #9399
Context
-------
Prior to this PR we were unable to build our Swift source code as part of the Bazel toolchain because our source supports CocoaPods-style framework imports out of the box. E.g.:
```swift
import MaterialComponents.MaterialAppBar
```
Supporting CocoaPods imports enables us to use a pure open source workflow with our code that ensures we're using and validating the latest community technologies (including CocoaPods and native Xcode build systems). Changing our source to Bazel-first was explored as an option for this PR, but was rejected in service to maintaining our CocoaPods support.
The way we solved this import problem before this PR was to perform a global rewrite of import statements prior to invoking any `bazel` commands. This rewrite phase happened as part of the `.kokoro` script. This meant that the only way to run `bazel` commands on our repo was through the `.kokoro` bootstrap script.
This change does not yet entirely remove our need for the `.kokoro` bootstrap script, but it does remove the need for it to rewrite Swift imports. This change is one part of #5491.
The change
----------
This change introduces a new drop-in replacement for swift_library called `_mdc_cocoapods_compatible_swift_library` (for private use within the `material_components_ios.bzl` file) and `mdc_swift_library` for use in all BUILD files. `_mdc_cocoapods_compatible_swift_library` is made use of by several `mdc_` rules, including the new `mdc_swift_library` rule which should now be used instead of `swift_library` throughout our repo.
The new rule's implementation is documented in the source.
The impact
----------
Prior to this change, running the following command:
```
bazel build //components/Typography:SwiftExamples
```
Would result in the following error:
```
components/Typography/examples/TypographyFontListExample.swift:15:8: error: no such module 'MaterialComponents.MaterialTypography'
import MaterialComponents.MaterialTypography
```
After this change, running that same command will give the following successful result:
```
INFO: Invocation ID: 324c8887-d733-42ce-be06-20d9823bf718
INFO: Build options have changed, discarding analysis cache.
INFO: Analysed target //components/Typography:SwiftExamples (3 packages loaded, 365 targets configured).
INFO: Found 1 target...
Target //components/Typography:SwiftExamples up-to-date:
bazel-bin/components/Typography/libSwiftExamples.a
bazel-bin/components/Typography/components_Typography_SwiftExamples.swiftdoc
bazel-bin/components/Typography/components_Typography_SwiftExamples.swiftmodule
INFO: Elapsed time: 4.299s, Critical Path: 4.01s
INFO: 2 processes: 2 darwin-sandbox.
INFO: Build completed successfully, 3 total actions
```
Note that as a result of this change, build output for the transformed src will point to the generated source files rather than the original source files. E.g.:
```
ERROR: /Users/featherless/workbench/material-components-ios/components/Typography/BUILD:55:1: SwiftCompile components/Typography/components_Typography_SwiftExamples.swiftmodule failed (Exit 1) bazel_xcode_wrapper failed: error executing command bazel-out/host/bin/external/build_bazel_rules_swift/tools/wrappers/bazel_xcode_wrapper bazel-out/host/bin/external/build_bazel_rules_swift/tools/wrappers/swift_wrapper /usr/bin/xcrun swiftc ... (remaining 3 argument(s) skipped)
Use --sandbox_debug to see verbose messages from the sandbox
bazel-out/darwin-fastbuild/genfiles/components/Typography/examples/TypographyFontListExample.bazel_imports.swift:20:1: error: expressions are not allowed at the top level
typo
^
bazel-out/darwin-fastbuild/genfiles/components/Typography/examples/TypographyFontListExample.bazel_imports.swift:20:1: error: use of unresolved identifier 'typo'
typo
^~~~
```
This is the downside to this change, but it only materially impacts eng workflows if we start using Bazel to generate Xcode projects. As command line output, it's fairly straightforward to transform the path to the correct original source path. If we do someday move to a Bazel-generated Xcode project workflow, then we should also revisit our assumption that our source should support CocoaPods out of the box. As noted at the beginning of this PR, however, this consideration is deemed out of scope for this PR.
This reverts commit ca81e6e42826956e1912665a8e8077ab0d9705be.
The reverted commit does not actually fix the ancestry problem for a given release and the change was adding an unnecessary merge operation as a result. Simply branching off of `develop` is sufficient to create history from `stable` to `develop`.
In a follow-up change, I will address the actual root problem of `develop` not having an ancestral relations to the `stable` release commits.
Prior to this change, our release process was merging `develop` directly into `stable` without first branching off of `stable`.
The result of this process was that `stable` shares no common ancestor with `develop`, making it difficult to calculate differences between a commit on `develop` and a commit on `stable`.
One example of where this becomes problematic is in generating internal CLs for our PRs and for `develop`. It is not possible to compute the delta between the most recent `stable` commit that was mirrored internally and a given `develop` commit, making it difficult for tooling to apply deltas to the internal codebase without simply blowing away the internal directory and checking out the desired `develop` commit.
To fix this problem, we need to create a common ancestor between `develop` and `stable`. To do so, when cutting a release we need to cut the `release-candidate` from `stable` rather than `develop`, and then immediately merge `develop` into the release-candidate. This creates a common ancestor between `develop` and `stable`.
Note that this change causes us to deviate from the pure git flow model we have historically been following, as shown in the before/after of the model below (note the new red lines connecting stable to develop).
| Before | After |
|:--|:--|
|  |  |
Instead of waiting until a bunch of work has been done to fix/update internal build issues, the `pod lib lint` step should happen as soon as the branch is created. This is because any potential issue caught by CocoaPods is likely to have a downstream effect on internal code.
Cutting a release can take time and can sometimes be challenging, so sharing status updates with the team as the release progresses ensures that the team is informed of the status of the release. This PR adds a note about communicating the status of the release to the team's internal chat room.
The first internal steps require some one-time set-up (in the future possibly repeated set-up) and shouldn't be skipped. Pointing the link to the Requirements section so those can be seen and attended to by the release engineer.
The emoji in the releasing documentation wasn't clear on its meaning/purpose. Particularly for people who don't know how to read emojis, the meaning is lost. Changing it to "optional" to make it clearer that it's a nice thing to do but not strictly required for releasing.
Fixes#7324
Follow-up to #7321
Our Beta instructions failed to have clients point the `MaterialComponents` pod target at the `develop` branch of our Git repository. This often results in a mismatch in code found in `develop` (for Beta) and `stable` (for the released versions).
Addresses issues seen in #6949
Brew is not a good option for bazel installs since it doesn't allow downgrading versions. We only support 0.20 at the moment, so clients should use the specific installer script for 0.20.
While the PR for a release is still an in-progress work, we need to add the correct marker to either the title or summary. Since the `[]` markers at the beginning of a title are reserved for component names, we can use `{}` markers instead for the same purpose.
Adding a new "setup" step for release engineers to run before cutting the
release. This step will be important to avoid merging changes to
`.gitattributes` from `develop` into `stable` and overwriting the custom
values there.
Documentation for #6350
Follow-up to #5956
Thanks to @codeman7 for his help getting me started on #6151. I found this hard enough to do on my own that I thought others might have trouble too. I realize there are many questions of taste that go into this sort of documentation:
- Does it belong here, or somewhere else?
- Are any of the steps too detailed, or not detailed enough?
- Does it start too early? In other words, would anybody who's reading this actually need the first few steps?
- Should I mention how to work around #5825 as a Known Issue, or should I assume that will get fixed soon enough that it isn't worth mentioning?
I'm assuming I don't have this written *exactly* the way you'd like it, so this PR is intended to start a discussion.
* [Release Docs] Highlighted creating release PR.
This change makes the action needed to be taken by release cop more prominent so that it is not skipped.
* Update contributing/releasing.md
Co-Authored-By: randallli <randallli@google.com>
The Sanity Check steps seem to be a bunch of required steps that aren't
necessary if the release engineer has followed the previous instructions.
Instead, it can be an optional set of helpful commands.
This change was automatically generated by running a find replace of the following strings:
```
mdc_unit_test_suite(
mdc_unit_test_suite(
name = "unit_tests",
```
And then running buildifier to enforce style:
find . -name BUILD | xargs ~/buildifier
This is an automated change generated by replacing all instances of MaterialComponentsAlpha with MaterialComponentsBeta. This is not a breaking change because changes to Alpha/Beta components (including renaming them) are not considered breaking.
The MaterialComponentsAlpha podspec was mistakenly named Alpha, when what we meant was more close to Beta. The distinction is that Alpha components are not expected to be used by clients, while Beta components are.
