diff --git a/gbm-cli/README.md b/gbm-cli/README.md index d55d1ac..d41e440 100644 --- a/gbm-cli/README.md +++ b/gbm-cli/README.md @@ -1,14 +1,22 @@ # GBM CLI ## Overview -The GBM cli tool helps developmental tasks for managing Gutenberg Mobile releases. +The GBM CLI tool helps developmental tasks for managing Gutenberg Mobile releases. The current features include: - Command to generate the release checklist - Commands to wrangle Gutenberg Mobile releases -## Prerequisites -Download and install the [Go package](https://go.dev/doc/install). +## Development Environment +1. Download and install the [Go package](https://go.dev/doc/install). +2. While not required, it is higly recommended to develop with [VSCode](https://code.visualstudio.com/) and install the [Go VSCode](https://marketplace.visualstudio.com/items?itemName=golang.go) extension. + +## Releasing +For detailed instructions on running a release, visit [Releasing.md](https://github.com/wordpress-mobile/release-toolkit-gutenberg-mobile/blob/cli/update-checklist/cli/Releasing.md). + +## Testing +For detailed instructions on testing and configuring your development environment, visit [Testing.md](https://github.com/wordpress-mobile/release-toolkit-gutenberg-mobile/blob/cli/update-checklist/cli/Testing.md). + ## Structure diff --git a/gbm-cli/Releasing.md b/gbm-cli/Releasing.md new file mode 100644 index 0000000..9116b39 --- /dev/null +++ b/gbm-cli/Releasing.md @@ -0,0 +1,128 @@ +# Release Checklist Template + +The Release Checklist Template can be generated with the following command: (replacing `X.XX.X` with the applicable release number): + +``` +go run main.go render checklist -v X.XX.X +``` + +The `--c` flag will copy the output to your clipboard. To view the output in the command line, simply remove the `--c` flag. + + +If the release is a betafix/hotfix, include a message explaining briefly the reason for releasing the fix. +**Example:** + +``` +go run main.go render checklist -v X.XX.X --message "This hotfix addresses ISSUE_OR_CRASH in ORIGINAL_VERSION. See P2_PR_SLACK_ETC_LINK_OR_LINKS for the rationale behind the decision to make it." +``` + +# Different types of releases + +## Best practices + +It's best practice to use the automation script (mentioned in the release template above) for all releases types (alpha, regular, betafix, hotfix). When wrangling a betafix or hotfix, it's important to merge the fix to Gutenberg `trunk` independently of the release process. When the release is cut (by the automation script) the commit(s) that make up the betafix or hotfix should then be cherry-picked onto the Gutenberg release branch. + +## 1. Alpha + +### When + +Whenever a build is needed for testing (usually a few days prior to a Regular release). + +### Branches + +For example, when the next release will be `1.11.0`. + +| Repo | Cut From | Branch Name | +| ---------------- | -------- | ----------------------------------------- | +| gutenberg | trunk | rnmobile/release_1.11.0-alpha1 | +| gutenberg-mobile | trunk | release/1.11.0-alpha1 | +| WPAndroid | trunk | gutenberg/integrate_release_1.11.0-alpha1 | +| WPiOS | trunk | gutenberg/integrate_release_1.11.0-alpha1 | + +### Automation script differences + +Compared to a Regular release, the differences here are: + +- When the script asks for the new version number, don't forget to add the `-alpha` suffix (e.g. `1.11.0-alpha1`). +- All PRs created by the release script should be edited to clarify that they are temporary and will be deleted when testing is finished. + +### Release checklist template differences + +The release checklist is not used for alpha releases. When testing is finished, please close all PRs and delete all branches created by the script. + +## 2. Regular + +### When + +On Thursdays, the week before the main apps (WPiOS & WPAndroid) have cut their releases, every 2 weeks. + +### Branches + +For example when releasing gutenberg-mobile `1.11.0`. + +| Repo | Cut From | Branch Name | Merging To | +| ---------------- | -------- | ---------------------------------- | --------------- | +| gutenberg | trunk | rnmobile/release_1.11.0 | trunk | +| gutenberg-mobile | trunk | release/1.11.0 | trunk | +| WPAndroid | trunk | gutenberg/integrate_release_1.11.0 | trunk | +| WPiOS | trunk | gutenberg/integrate_release_1.11.0 | trunk | + +## 3. Betafix + +### When + +A fix is targeting a main app version that is not yet released (meaning the release branch is cut but it's still in beta) and a new gutenberg-mobile release is needed. + +### Branches + +For example when releasing gutenberg-mobile `1.11.1` while main apps version `22.2.0` is in beta which currently has gutenberg-mobile `1.11.0` in it. +At the same time there could also be a regular release going on for example for gutenberg-mobile version `1.12.0`. + +| Repo | Cut From | Branch Name | Merging To | +| ---------------- | ----------------------- | ---------------------------------- | ---------------------------------------------------------------- | +| gutenberg | rnmobile/release_1.11.0 (tag) | rnmobile/release_1.11.1 | trunk & (maybe also) rnmobile/release_1.12.0 | +| gutenberg-mobile | v1.11.0 (tag) | release/1.11.1 | trunk & (maybe also) release/1.12.0 | +| WPAndroid | release/22.2.0 | gutenberg/integrate_release_1.11.1 | release/22.2.0 & (maybe also) gutenberg/integrate_release_1.12.0 | +| WPiOS | release/22.2.0 | gutenberg/integrate_release_1.11.1 | release/22.2.0 & (maybe also) gutenberg/integrate_release_1.12.0 | + +### Automation script differences + +1. Run the CLI tool as normal +1. When asked by the script enter the relevant branch names to cut from (to target) in other repos. +1. If a commit that is fixing the issue is already merged to gutenberg, when asked by the script enter the commit hash to be cherry-picked. + +### Release checklist template differences + +1. Include `Betafix` in the heading. +1. `after_X.XX.X` branches can be ignored. + +## 4. Hotfix + +### When + +A fix is targeting a main app version that is already released and a new gutenberg-mobile release is needed. + +### Branches + +For example when releasing gutenberg-mobile `1.11.1` while main apps version `22.2.0` is released which currently has gutenberg-mobile `1.11.0` in it. +At the same time there could also be a regular release, a betafix or even another hotfix going on for example for gutenberg-mobile version `1.12.1`. + +| Repo | Cut From | Branch Name | Merging To | +| ---------------- | ----------------------- | ---------------------------------- | ---------------------------------------------------------------- | +| gutenberg | rnmobile/release_1.11.0 (tag) | rnmobile/release_1.11.1 | trunk & (maybe also) rnmobile/release_1.12.1 | +| gutenberg-mobile | v1.11.0 (tag) | release/1.11.1 | trunk & (maybe also) release/1.12.1 | +| WPAndroid | release/22.2.0 | gutenberg/integrate_release_1.11.1 | release/22.2.1 & (maybe also) gutenberg/integrate_release_1.12.1 | +| WPiOS | release/22.2.0 | gutenberg/integrate_release_1.11.1 | release/22.2.1 & (maybe also) gutenberg/integrate_release_1.12.1 | + +### Automation script differences + +1. If necessary create new patch version branches `release/X.Y.1` in WPiOS and WPAndroid. + +The rest should be same the as Betafix. + +### Release checklist template differences + +1. Include `Hotfix` in the heading +1. After the fix is merged and if there is an ongoing regular release, betafix or hotfix then the changes should be brought back to those branches as well. + +The rest should be same the as Betafix. \ No newline at end of file diff --git a/gbm-cli/Testing.md b/gbm-cli/Testing.md new file mode 100644 index 0000000..d06d330 --- /dev/null +++ b/gbm-cli/Testing.md @@ -0,0 +1,30 @@ +# Testing + +If developing with VSCode, tests can be run inline within the test files themselves, and is the recommended method for running and debugging tests. Tests can also be run from the command line with the `go test` command. + +## Testing Environment for Development +The CLI tool can be run against forked repos for testing. To configure your forked repos: + + 1. Fork the following repos to your github user repo: + - [Gutenberg-Mobile](https://github.com/wordpress-mobile/gutenberg-mobile) + - [Gutenberg](https://github.com/WordPress/gutenberg) + - [WordPress-Android](https://github.com/wordpress-mobile/WordPress-Android) + - [WordPress-iOS](https://github.com/wordpress-mobile/WordPress-iOS) + +3. Ensure that your forked repos contains the PR labels specified below: + a) Gutenberg Mobile: "release-process" + b) Gutenberg: "Mobile App - i.e. Android or iOS" + +4. Ensure that each of your repos contains the target branch `trunk`. + +5. Ensure that [.gitmodules](https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/.gitmodules) references your Gutenberg fork. + + +To run commands against the forked repos, set `GBM_WORDPRESS_ORG` and `GBM_WPMOBILE_ORG` as environment variables to user GitHub username. By default, these values with be WordPress and WordPress-Mobile, respectively. + +Example command: + +``` +GBM_WPMOBILE_ORG=yourusername GBM_WORDPRESS_ORG=yourusername go run main.go release prepare gb 1.109.0 +``` + diff --git a/gbm-cli/cmd/render/checklist.go b/gbm-cli/cmd/render/checklist.go index 705c9c6..d189e51 100644 --- a/gbm-cli/cmd/render/checklist.go +++ b/gbm-cli/cmd/render/checklist.go @@ -70,6 +70,7 @@ var ChecklistCmd = &cobra.Command{ Scheduled: scheduled, ReleaseUrl: releaseUrl, Date: releaseDate, + Message: message, HostVersion: hostVersion, IncludeAztec: includeAztec, CheckAztec: checkAztec, diff --git a/gbm-cli/templates/checklist/checklist.html b/gbm-cli/templates/checklist/checklist.html index 6046d30..10da18c 100644 --- a/gbm-cli/templates/checklist/checklist.html +++ b/gbm-cli/templates/checklist/checklist.html @@ -37,13 +37,11 @@

Before the Release (Tuesday)

Create the Release{{ if .Scheduled }} (Thursday) {{end}}

-{{ Task `Verify that gutenberg-mobile/RNTAztecView.podspec and gutenberg-mobile/gutenberg/packages/react-native-aztec/RNTAztecView.podspec - refer to the same WordPress-Aztec-iOS version and are pointing to a stable, tagged release (e.g. 1.14.1). If they are not, we may need to create a new Aztec release.` }} +{{ Task `Pull the latest version of the CLI.` }} -{{ Task `Clone the release scripts or pull the latest version if you have already cloned it.` }} +{{ Task `In your clone of the cli directory, run the prepare command: go run main.go release prepare all %s to create the gutenberg and gutenberg-mobile release PRs.` }} -{{ Task `Review the release script instructions. - In your clone of the release scripts, run the script via: ./release_automation.sh. This creates the gutenberg and gutenberg-mobile release PRs as well as WPAndroid and WPiOS integration PRs.` }} +{{ Task `Once the CI tasks succeed, run the integrate command to create the main apps PRs for WordPress-iOS and WordPress-Android: go run main.go release integrate %s `}} {{ if .Scheduled }} @@ -60,17 +58,6 @@

Create the Release{{ if .Scheduled }} (Thursday) {{end}}

{{ end }} -{{ Task `In both RELEASE-NOTES.txt and gutenberg/packages/react-native-editor/CHANGELOG.md, - replace Unreleased section with the release version and create a new Unreleased section.` }} - -{{ Task `Review and update RELEASE-NOTES.txt file on both WPAndroid and WPiOS PRs so it includes all user-facing changes introduced in the release. - Keep in mind that some changes can be specific to a single platform, so they should only be added to the release notes of the platform that affects - (e.g. a change that only affects Android should only be included in WPAndroid release notes).` }} - -{{ Task `Verify the WPAndroid and WPiOS PR builds succeed. For WPAndroid, if the PR CI tasks include a 403 error related to an inability to resolve the - react-native-bridge dependency, you must wait for the Build Android RN Bridge & Publish to S3 - task to succeed in gutenberg-mobile and then restart the WPAndroid CI tasks. Similarly, for iOS, you must wait for the Build iOS RN XCFramework & Publish to S3 task to succeed.` }} - {{ Task `Once the installable builds are ready, perform a quick smoke test of the editor on both iOS and Android to verify it launches without crashing. We will perform additional testing after the main apps cut their releases.` }} @@ -112,15 +99,9 @@

Manage Incoming Changes (conditional)

{{ Task `Add the new change to the "Extra PRs that Landed After the Release Was Cut" section of the gutenberg-mobile PR description.` }} -

Integrate the Release{{ if .Scheduled }} (Thursday) {{end}}

+

Publish the Release{{ if .Scheduled }} (Thursday) {{end}}

-{{ Task `Verify the gutenberg ref within the gutenberg-mobile release branch is pointed to the latest commit in the gutenberg release branch.` }} - -{{ Task `Create and push a rnmobile/%s git tag for the head of gutenberg release branch.` .Version }} - -{{ Task `Ensure that the bundle files are updated to include any changes to the release branch by running npm run bundle in gutenberg-mobile release branch and committing any changes.` }} - {{ Task `Create a new gutenberg-mobile GitHub Release. Include a list of changes in the release description. Ensure the checkmark "Set as the latest release" is checked, and publish the release with the "Publish release" button.` .ReleaseUrl }} {{ Task `Wait until all CI jobs for the published tag finish and succeed.` }}