docs/git_workflow.md

 # 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.

## Branchless workflow

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.