README cleanup
Change-Id: I47f3a41a29bb53a4a57ad79969e21fda0943e08f
Reviewed-on: https://flutter-review.googlesource.com/c/recipes/+/49881
Commit-Queue: Christopher Fujino <fujino@google.com>
Reviewed-by: Christopher Fujino <fujino@google.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d1313b4..9e96ae6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,61 +15,74 @@
For additional context please read the Flutter's [CONTRIBUTING document](https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md).
-Sign in to Gerrit (one time)
-------------------------------
+Initial setup
+-------------
+
+### Sign in to Gerrit
Gerrit is a free, web-based team code collaboration tool. Software developers in a team can review each other's
modifications on their source code using a Web browser and approve or reject those changes. It integrates closely
with Git, a distributed version control system. Flutter uses Gerrit/Git for source code control to take advantage
of the existent LUCI integrations.
-Note: git client must be pre-installed in your system.
+A `git` client must be pre-installed in your system.
Visit [Flutter's Gerrit Host](https://flutter-review.googlesource.com/) and click the sign in link on the
top right section of the page.
-Create a gerrit account (one time)
---------------------------------
+
+### Create a gerrit account
Visit the [Settings page of the Flutter Gerrit Host](https://flutter-review.googlesource.com/settings/). It will
offer to create a gerrit account, follow the on screen instructions to create the account.
-Generate passwords (one time)
------------------------------
+### Generate passwords
Visit the [Settings page of the Flutter Gerrit Host](https://flutter-review.googlesource.com/settings/). Scroll
down close to the bottom and click on the `obtain password link`, click on allow, copy the command from the new window
and run it on your git terminal. This will cache your credentials in your local environment.
-Sign CLA (one time)
-------------------
+
+### Sign CLA
Visit the [Settings page of the Flutter Gerrit Host](https://flutter-review.googlesource.com/settings/). Scroll down
close to the bottom and click on the `new contributor agreement` link, select Google CLA, review the CLA and accept the
agreement.
-Create a change list
---------------------
+### Check out the repository
-Please ensure you have created a gerrit account, generated passwords (ran the associated commands) and accepted
-the CLA before running the next commands.
+Finally you can finish your setup by cloning the git repository:
+
+```
+git clone https://flutter.googlesource.com/recipes
+cd recipes
+```
+
+Creating a change list (pull request)
+-------------------------------------
+
+Once you have created a gerrit account, generated passwords (ran the associated commands), and accepted
+the CLA, you can start submitting a CL (change list, what Gerrit calls PRs).
The following commands can be used to create a new change list and sent it for review:
```
-git clone https://flutter.googlesource.com/recipes # clone the repository.
-cd recipes
git checkout -b <new_branch>
-# git add <file> or git rm <file>
+# prepare your patch, run git add <files> or git rm <files> as appropriate
git commit
git push origin HEAD:refs/for/main
+```
-# The commands below need to be executed once on the first CL to the repository.
-# If this is your first CL and you get an error related to "missing Change-Id in message footer"
-# run the command provided in the hint section above the error. This is is required only in the first
-# CL to enable the hook to automatically add a change ID to the CL.
-# git commit --amend --no-edit
-# git push origin HEAD:refs/for/main
-````
+If this is your first CL and you get an error related to "missing Change-Id in message footer",
+run the command provided in the hint section above the error. This is is required only in the first
+CL to enable the hook to automatically add a change ID to the CL.
+
+Then, run the following commands to attempt to submit the CL again:
+
+```
+git commit --amend --no-edit
+git push origin HEAD:refs/for/main
+```
+
diff --git a/README.md b/README.md
index 590e088..f2036db 100644
--- a/README.md
+++ b/README.md
@@ -21,5 +21,8 @@
Running `python3 recipes.py test train` will execute all of the tests in this repository
## Troubleshooting
-### `Required binary is not found on PATH: cipd` when testing locally
-You need to ensure [depot_tools](https://chromium.googlesource.com/chromium/tools/depot_tools.git) is installed. See [Depot Tools Installation Tutorial](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)
+
+### "Required binary is not found on PATH: cipd" when testing locally
+
+You need to ensure [depot_tools](https://chromium.googlesource.com/chromium/tools/depot_tools.git) is installed.
+See the [Depot Tools Installation Tutorial](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up).
