From a3881dec22483fb14e7aece83ed9d1da61325849 Mon Sep 17 00:00:00 2001 From: Elliott Brooks <21270878+elliette@users.noreply.github.com> Date: Mon, 9 Jan 2023 11:32:06 -0800 Subject: [PATCH 1/3] Add hotfix instructions --- dwds/CONTRIBUTING.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/dwds/CONTRIBUTING.md b/dwds/CONTRIBUTING.md index 4ffa5559a..0a07c6d4c 100644 --- a/dwds/CONTRIBUTING.md +++ b/dwds/CONTRIBUTING.md @@ -138,3 +138,42 @@ you need to: > run tests for all earlier stable releases of the SDK that match the > constraint, which would have differences in functionality and therefore need > different tests. + +## Hotfixes + +Sometimes you might need to do a hotfix release of DWDS. An example of why this +might be necessary is if you need to do a hotfix of DWDS into Flutter, but don't +want to release a new version of DWDS with the current untested changes on the +master branch. Instead you only want to apply a fix to the current version of +DWDS in Flutter. + +### Instructions: + +1. In the Github UI's + [commit history view](https://github.com/dart-lang/webdev/commits/master), + find the commit that prepared the release of DWDS that you would like to + hotfix. +1. Click on `< >` ("Browse the repository at this point in history"). +1. At the top-left, you should see the commit hash in a dropdown. Click the + dropdown, and type in a name for your hotfix branch (e.g. + `16.0.2-hotfix-release`). Then select "Create branch `16.0.2-hotfix-release` + from `commit_hash`". +1. From your local clone of DWDS, run `git fetch upstream`. (*Note: this assumes + you have already configured git to sync your fork with the `upstream` + repository. If you haven't, follow + [these instructions](https://docs.github.com/en/get-started/quickstart/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository).)* +1. Search for the branch that you just created, e.g. + `git branch -a | grep 16.0.2-hotfix-release` +1. Track that branch with `git checkout --track branch_name` (e.g. + `remotes/upstream/16.0.2-hotfix-release`) +1. You can now make the change you would like to hotfix on the branch you have. + When you are done, push it to Github (eg, + `git push origin 16.0.2-hotfix-release`). +1. Now, from the Github UI, open a PR to merge your change into the branch you + created in step #3, **not** `master`. See + https://github.com/dart-lang/webdev/pull/1867 as an example. +1. Once it's merged, you can follow the instructions to + [publish DWDS to pub](#step-2-publish-dwds-to-pub), except instead of pulling + from `master`, pull from the branch your created in step #3. +1. If necessary, open a cherry-pick request in Flutter to update the version. + See https://github.com/flutter/flutter/issues/118122 for an example. From 2db2ab96efb3c7d28fdbbcadeea7a57f6aa3d6c5 Mon Sep 17 00:00:00 2001 From: Elliott Brooks <21270878+elliette@users.noreply.github.com> Date: Mon, 9 Jan 2023 14:46:41 -0800 Subject: [PATCH 2/3] Respond to PR comments --- dwds/CONTRIBUTING.md | 62 ++++++++++++++++++++++++++------------------ 1 file changed, 37 insertions(+), 25 deletions(-) diff --git a/dwds/CONTRIBUTING.md b/dwds/CONTRIBUTING.md index 0a07c6d4c..a75f746af 100644 --- a/dwds/CONTRIBUTING.md +++ b/dwds/CONTRIBUTING.md @@ -19,8 +19,8 @@ alias flutter_tools='/YOUR_PATH/flutter/bin/dart --observe /YOUR_PATH/flutter/pa > - `/PATH_TO_YOUR_FLUTTER_REPO/packages/flutter_tools/bin/flutter_tools.dart`: > This is the path to Flutter Tools itself > -> *More details can be found at the Flutter Tools -> [README](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/README.md).* +> _More details can be found at the Flutter Tools +> [README](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/README.md)._ 3. In your Flutter Tools [`pubspec.yaml`](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/pubspec.yaml), @@ -73,8 +73,8 @@ the example app and connect to DWDS. ### Step 1: Roll DWDS into g3 -> *NOTE: You must be a Googler to do this step. If you are not, please ask -> someone for help.* +> _NOTE: You must be a Googler to do this step. If you are not, please ask +> someone for help._ - See directions at: go/roll-dwds - Wait a few days after rolling into g3 before continuing to step 2. We do so to @@ -91,21 +91,21 @@ the example app and connect to DWDS. - From `/dwds` run `dart run build_runner build`, this will build and update the version in `/dwds/lib/src/version.dart` - Submit a PR with those changes (example PR: - https://github.com/dart-lang/webdev/pull/1456). *Note: Ensure your PR doesn’t - have any dependency overrides.* + https://github.com/dart-lang/webdev/pull/1456). _Note: Ensure your PR doesn’t + have any dependency overrides._ - Once the PR is submitted, pull from master and `run dart pub publish` - Finally, go to https://github.com/dart-lang/webdev/releases and create a new release, eg https://github.com/dart-lang/webdev/releases/tag/dwds-v12.0.0. You might need to delete some of the content of the autogenerated notes. -> *Note: To have the right permissions for publishing, you need to be invited to +> _Note: To have the right permissions for publishing, you need to be invited to > the tools.dart.dev. A member of the Dart team should be able to add you at -> https://pub.dev/publishers/tools.dart.dev/admin.* +> https://pub.dev/publishers/tools.dart.dev/admin._ ## Step 3: Publish Webdev to pub -> *Note: DWDS is a dependency of Webdev, which is why DWDS must be published -> before Webdev can be published.* +> _Note: DWDS is a dependency of Webdev, which is why DWDS must be published +> before Webdev can be published._ Follow instructions in the `webdev/webdev` [CONTRIBUTING](/webdev/CONTRIBUTING.md) to release Webdev. @@ -149,31 +149,43 @@ DWDS in Flutter. ### Instructions: -1. In the Github UI's +1. Create a branch off the release that needs a hotfix: + + a. In the Github UI's [commit history view](https://github.com/dart-lang/webdev/commits/master), find the commit that prepared the release of DWDS that you would like to hotfix. -1. Click on `< >` ("Browse the repository at this point in history"). -1. At the top-left, you should see the commit hash in a dropdown. Click the + + b. Click on `< >` ("Browse the repository at this point in history"). + + c. At the top-left, you should see the commit hash in a dropdown. Click the dropdown, and type in a name for your hotfix branch (e.g. `16.0.2-hotfix-release`). Then select "Create branch `16.0.2-hotfix-release` from `commit_hash`". -1. From your local clone of DWDS, run `git fetch upstream`. (*Note: this assumes - you have already configured git to sync your fork with the `upstream` + + d. From your local clone of DWDS, run `git fetch upstream`. (_Note: this + assumes you have already configured git to sync your fork with the `upstream` repository. If you haven't, follow - [these instructions](https://docs.github.com/en/get-started/quickstart/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository).)* -1. Search for the branch that you just created, e.g. - `git branch -a | grep 16.0.2-hotfix-release` -1. Track that branch with `git checkout --track branch_name` (e.g. + [these instructions](https://docs.github.com/en/get-started/quickstart/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository).)_ + + e. Search for the branch that you just created, e.g. + `git branch -a | grep 16.0.2-hotfix-release` f. Track that branch with + `git checkout --track branch_name` (e.g. `remotes/upstream/16.0.2-hotfix-release`) -1. You can now make the change you would like to hotfix on the branch you have. - When you are done, push it to Github (eg, - `git push origin 16.0.2-hotfix-release`). -1. Now, from the Github UI, open a PR to merge your change into the branch you - created in step #3, **not** `master`. See - https://github.com/dart-lang/webdev/pull/1867 as an example. + +1. Update the CI tests so that the branch tests against the appropriate Dart + SDKs. a. Make the appropriate changes to DWDS' `mono_pkg.yaml` then run + `mono_repo generate`. Submit this change to the branch you created in step + #3, **not** `master`. + +1. You can now make the change you would like to hotfix. From the Github UI, + open a PR to merge your change into the branch you created in step #3, + **not** `master`. See https://github.com/dart-lang/webdev/pull/1867 as an + example. + 1. Once it's merged, you can follow the instructions to [publish DWDS to pub](#step-2-publish-dwds-to-pub), except instead of pulling from `master`, pull from the branch your created in step #3. + 1. If necessary, open a cherry-pick request in Flutter to update the version. See https://github.com/flutter/flutter/issues/118122 for an example. From f42603d32a2bde69bc42b9baec6b1febb8f840d0 Mon Sep 17 00:00:00 2001 From: Elliott Brooks <21270878+elliette@users.noreply.github.com> Date: Mon, 9 Jan 2023 14:51:24 -0800 Subject: [PATCH 3/3] Clean up --- dwds/CONTRIBUTING.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/dwds/CONTRIBUTING.md b/dwds/CONTRIBUTING.md index a75f746af..ae3abaa37 100644 --- a/dwds/CONTRIBUTING.md +++ b/dwds/CONTRIBUTING.md @@ -174,11 +174,15 @@ DWDS in Flutter. `remotes/upstream/16.0.2-hotfix-release`) 1. Update the CI tests so that the branch tests against the appropriate Dart - SDKs. a. Make the appropriate changes to DWDS' `mono_pkg.yaml` then run + SDKs: + + a. Make the appropriate changes to DWDS' `mono_pkg.yaml` then run `mono_repo generate`. Submit this change to the branch you created in step #3, **not** `master`. -1. You can now make the change you would like to hotfix. From the Github UI, +1. Make the fix: + + a. You can now make the change you would like to hotfix. From the Github UI, open a PR to merge your change into the branch you created in step #3, **not** `master`. See https://github.com/dart-lang/webdev/pull/1867 as an example.