From bbed373f3200df1efed266d161ee34bc52e6306d Mon Sep 17 00:00:00 2001 From: Michael Klimushyn Date: Mon, 25 Nov 2019 12:52:36 -0800 Subject: [PATCH 1/2] [none] Add release process to CONTRIBUTING.md This provides information on how to publish plugins going forward with the new `flutter_plugin_tools publish-plugin` command. In addition to that this documents our general process, which is a general team health issue we've been wanting for awhile. DO NOT MERGE until `flutter_plugin_tools publish-plugin` has been merged and released. --- CONTRIBUTING.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7edb13c08e60..30d283aaee6d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -147,3 +147,69 @@ Newly opened PRs first go through initial triage which results in one of: * **Starting a non trivial review** - if the review requires non trivial effort and the issue is a priority; in this case the maintainer will: * Add the "in review" label to the issue. * Self assign the PR. + +### The release process + +We push releases manually. Generally every merged PR upgrades at least one +plugin's `pubspec.yaml`, so also needs to be published as a package release. The +Flutter team member most involved with the PR should be the person responsible +for publishing the package release. In cases where the PR is authored by a +Flutter maintainer, the publisher should probably be the author. In other cases +where the PR is from a contributor, it's up to the reviewing Flutter team member +to publish the release instead. + +Some things to keep in mind before publishing the release: + +- Has CI ran on the master commit and gone green? Even if CI shows as green on + the PR it's still possible for it to fail on merge, for multiple reasons. + There may have been some bug in the merge that introduced new failures. CI + runs on PRs as it's configured on their branch state, and not on tip of tree. + CI on PRs also only runs tests for packages that it detects have been directly + changed, vs running on every single package on master. +- [Publishing is + forever.](https://dart.dev/tools/pub/publishing#publishing-is-forever) + Hopefully any bugs or breaking in changes in this PR have already been caught + in PR review, but now's a second chance to revert before anything goes live. +- "Don't deploy on a Friday." Consider carefully whether or not it's worth + immediately publishing an update before a stretch of time where you're going + to be unavailable. There may be bugs with the release or questions about it + from people that immediately adopt it, and uncovering and resolving those + support issues will take more time if you're unavailable. + +Releasing a package is a two-step process. + +1. Push the package update to [pub.dev](https://pub.dev). +2. Tag the commit with git in the format of `-v`, + and then push the tag to `flutter/plugins` master branch. + +We've recently updated +[flutter_plugin_tools](https://github.com/flutter/plugin_tools) to wrap both of +those steps into one command to make it a little easier. Install the tool by +running: + +```terminal +$ pub global activate flutter_plugin_tools +``` + +Then, from the root of your local `flutter/plugins` repo, use the tool to +publish a release. + +```terminal +$ pub global run flutter_plugin_tools publish-plugin --package $package +``` + +By default the tool tries to push tags to the `upstream` remote, but that and +some additional settings can be configured. Run `pub global activate +flutter_plugin_tools --help` for more usage information. + +The tool wraps `pub publish` for pushing the package to pub, and then will +automatically use git to try and create and push tags. It has some additional +safety checking around `pub publish` too. By default `pub publish` publishes +_everything_, including untracked or uncommitted files in version control. +`flutter_plugin_tools publish-plugin` will first check the status of the local +directory and refuse to publish if there are any mismatched files with version +control present. + +There is a lot about this process that is still to be desired. Some top level +items are being tracked in +[flutter/flutter#27258](https://github.com/flutter/flutter/issues/27258). From 7c413410a063362ce178b95db513efc58ed43f6d Mon Sep 17 00:00:00 2001 From: Michael Klimushyn Date: Mon, 25 Nov 2019 14:55:20 -0800 Subject: [PATCH 2/2] Update with suggestion from Amir offline Note that the flutter_plugin_tools command is new, and add some information on how to release manually if needed. --- CONTRIBUTING.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30d283aaee6d..f58dfea6a065 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -178,14 +178,19 @@ Some things to keep in mind before publishing the release: Releasing a package is a two-step process. -1. Push the package update to [pub.dev](https://pub.dev). +1. Push the package update to [pub.dev](https://pub.dev) using `pub publish`. 2. Tag the commit with git in the format of `-v`, - and then push the tag to `flutter/plugins` master branch. + and then push the tag to the `flutter/plugins` master branch. This can be + done manually with `git tag $tagname && git push upstream $tagname` while + checked out on the commit that updated `version` in `pubspec.yaml`. We've recently updated [flutter_plugin_tools](https://github.com/flutter/plugin_tools) to wrap both of -those steps into one command to make it a little easier. Install the tool by -running: +those steps into one command to make it a little easier. This new tool is +experimental. Feel free to fall back on manually running `pub publish` and +creating and pushing the tag in git if there are issues with it. + +Install the tool by running: ```terminal $ pub global activate flutter_plugin_tools