Merge "[embedder] Add script to update Fuchsia SDK." into main
diff --git a/README.md b/README.md
index d11be1b..b0d5fd6 100644
--- a/README.md
+++ b/README.md
@@ -106,3 +106,82 @@
```sh
$FUCHSIA_EMBEDDER_DIR/scripts/sync_engine_artifacts_to_revision.sh $(cat $FUCHSIA_EMBEDDER_DIR/third_party/dart-pkg/internal/flutter/flutter/bin/internal/engine.version)
```
+
+## Uploading changes for review
+
+flutter-embedder reviews are handled using Gerrit at https://fuchsia-review.googlesource.com, which uses a single commit per
+code review. See
+[this guide](https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes)
+for an intro to Gerrit.
+
+An alternative Gerrit workflow is a branchless workflow where you do all your work
+from `origin/main` without creating new branches. We describe such a workflow below,
+but it's not mandatory, it's just provided as an example.
+
+An example branchless workflow for creating a new change is:
+
+```sh
+# Start work from an up-to-date main branch.
+git fetch origin
+git checkout origin/main
+# Modify some files...
+...
+# Stage and commit your changes.
+git add file1.cc file2.h
+git commit -m "[embedder] My cool new feature."
+# Upload for review.
+git push origin HEAD:refs/for/main
+```
+
+An example branchless workflow to apply feedback during a code review is:
+
+1. Visit https://fuchsia-review.googlesource.com and find your change.
+2. Select `... > Download patch > Checkout` and copy the command.
+3. Run the following commands:
+
+ ```sh
+ # Start from main with your change on top.
+ <paste the command you copied above>
+ # Make some changes to some files to apply the feedback...
+ ...
+ # Stage and amend your changes to your commit.
+ git add file1.cc file2.h
+ git commit --amend
+ # Upload your updated change for review.
+ git push origin HEAD:refs/for/main
+ ```
+
+An example branchless workflow to create a chain of changes is:
+
+```sh
+# Start work from an up-to-date main branch.
+git fetch origin
+git checkout origin/main
+# Modify some files...
+...
+# Stage and commit your changes.
+git add file1.cc file2.h
+git commit -m "[embedder] My cool new feature 1."
+# Upload for review.
+git push origin HEAD:refs/for/main
+# Do some more work on top of your cool new feature.
+git add file3.cc file4.h
+git commit -m "[embedder] My cool new feature 2."
+# Create a second code review for your second feature.
+# The second code review will only show changes for
+# your second feature and it will indicate that it is based on
+# top of the first feature.
+git push origin HEAD:refs/for/main
+```
+
+A branchless workflow comes with some benefits:
+
+1. It reduces the amount of local branches you have to track.
+2. It reduces the amount of local branches you have to clean up after submission.
+3. It reduces the amount of overhead to starting new work (just `git checkout origin/main`).
+
+However a branchless workflow also prevents you from storing multiple
+chains of commits locally. Uploading your changes to https://fuchsia-review.googlesource.com
+frequently can help address that problem, as https://fuchsia-review.googlesource.com then
+acts as the storage for each of your ongoing changes. This also keeps your changes in a
+state where they're easy to share and hand off to other people.
