Change in ...coreboot[master]: Documentation/lessons: Tidy up lesson 2 - coreboot-gerrit

16 May 2019

Jacob Garber has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/32804
Change subject: Documentation/lessons: Tidy up lesson 2
......................................................................
Documentation/lessons: Tidy up lesson 2
- The link to create an account is now "Sign in" and not "Register"
- Use monospace formatting for terminal commands and file names
- Properly escape less-than and greater-than
- Correct the 'make lint' example command
- Reformat example commit messages
- Add formatting for website links
- Other whitespace fixes
Signed-off-by: Jacob Garber jgarber1@ualberta.ca
Change-Id: I9931bef8c30387d1c08b59973d6de9b5c0419814
---
M Documentation/lessons/lesson2.md
1 file changed, 52 insertions(+), 44 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/04/32804/1

diff --git a/Documentation/lessons/lesson2.md b/Documentation/lessons/lesson2.md
index d6f800c..b952280 100644
--- a/Documentation/lessons/lesson2.md
+++ b/Documentation/lessons/lesson2.md
@@ -5,10 +5,10 @@
 If you already have an account, skip to Part 2.
Otherwise, go to https://review.coreboot.org in your preferred web browser.
-Select **Register** in the upper right corner.
+Select **Sign in** in the upper right corner.
Select the appropriate sign-in. For example, if you have a Google account,
-select **Google OAuth2** (gerrit-oauth-provider plugin)".**Note:** Your
+select **Google OAuth2** (gerrit-oauth-provider plugin). **Note:** Your
 username for the account will be the username of the account you used to
 sign-in with. (ex. your Google username).
@@ -17,7 +17,7 @@
 If you prefer to use an HTTP password instead, skip to Part 2b.
For the most up-to-date instructions on how to set up SSH keys with Gerrit go to
-https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.2/user-upload.html#configure_ssh)
+https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.2/user-upload.html#configure_ssh
 and follow the instructions there. Then, skip to Part 3.
Additionally, that section of the Web site provides explanation on starting
@@ -35,13 +35,13 @@
 In the upper right corner, select your name and click on **Settings**.
 Select **SSH Public Keys** on the left-hand side.
-In a terminal, run "ssh-keygen" and confirm the default path ".ssh/id_rsa".
+In a terminal, run `ssh-keygen` and confirm the default path `.ssh/id_rsa`.
Make a passphrase -- remember this phrase. It will be needed whenever you use
 this RSA Public Key. **Note:** You might want to use a short password, or
 forego the password altogether as you will be using it very often.
-Open "id_rsa.pub", copy all contents and paste into the textbox under
+Open `id_rsa.pub`, copy all contents and paste into the textbox under
 "Add SSH Public Key" in the https://review.coreboot.org webpage.
## Part 2b: Setting up an HTTP Password
@@ -51,7 +51,7 @@
 than selecting **SSH Public Keys**, select **HTTP Password**.
Click **Generate Password**. This should fill the "Password" box with a password. Copy
-the password, and add the following to your $HOME/.netrc file:
+the password, and add the following to your `$HOME/.netrc` file:
machine review.coreboot.org login YourUserNameHere password YourPasswordHere
@@ -61,7 +61,7 @@
 ## Part 3: Clone coreboot and configure it for submitting patches
On Gerrit, click on the **Browse** tab in the upper left corner and select
-**Repositories**.  From the listing, select the "coreboot" repo.  You may have
+**Repositories**. From the listing, select the "coreboot" repo. You may have
 to click the next page arrow at the bottom a few times to find it.
If you are using SSH keys, select **ssh** from the tabs under "Project
@@ -69,7 +69,7 @@
 This should prompt you for your id_rsa passphrase, if you previously set one.
If you are using HTTP, instead, select **http** from the tabs under "Project coreboot"
-and run the command that appears
+and run the command that appears.
Now is a good time to configure your global git identity, if you haven't
 already.
@@ -87,13 +87,13 @@
An easy first commit to make is fixing existing checkpatch errors and warnings
 in the source files. To see errors that are already present, build the files in
-the repository by running 'make lint' in the coreboot directory. Alternatively,
-if you want to run 'make lint' on a specific directory, run:
+the repository by running `make lint` in the coreboot directory. Alternatively,
+if you want to run `make lint` on a specific directory, run:
-	for file in $(git ls-files | grep src/amd/quadcore); do \
+	for file in $(git ls-files | grep <filepath>); do \
    util/lint/checkpatch.pl --file $file --terse; done
-where <filepath> is the filepath of the directory (ex. src/cpu/amd/car).
+where `filepath` is the filepath of the directory (ex. `src/cpu/amd/car`).
Any changes made to files under the src directory are made locally,
 and can be submitted for review.
@@ -116,7 +116,7 @@
    git commit -s
**Note:** The -s adds a signed-off-by line by the committer. Your commit should be
-signed off with your name and email (i.e. **Your Name** **<Your Email>**, based on
+signed off with your name and email (i.e. **Your Name** **<Your Email>**, based on
 what you set with git config earlier).
Running git commit first checks for any errors and warnings using lint. If
@@ -130,65 +130,73 @@
 one-line description of what you changed in the files using the template
 below:
-`<filepath>: Short description`
-*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors*
+    <filepath>: Short description
+
+For example,
+
+    cpu/amd/pi/00630F01: Fix checkpatch warnings and errors
**Note:** It is good practice to use present tense in your descriptions
 and do not punctuate your summary.
Then hit Enter. The next paragraph should be a more in-depth explanation of the
 changes you've made to the files. Again, it is good practice to use present
-tense.
-*ex.  Fix space prohibited between function name and open parenthesis,
-line over 80 characters, unnecessary braces for single statement blocks,
-space required before open brace errors and warnings.*
+tense. Ex.
+
+    Fix space prohibited between function name and open parenthesis,
+    line over 80 characters, unnecessary braces for single statement blocks,
+    space required before open brace errors and warnings.
When you have finished writing your commit message, save and exit the text
 editor. You have finished committing your change. If, after submitting your
-commit, you wish to make changes to it, running "git commit --amend" allows
+commit, you wish to make changes to it, running `git commit --amend` allows
 you to take back your commit and amend it.
-When you are done with your commit, run 'git push' to push your commit to
+When you are done with your commit, run `git push` to push your commit to
 coreboot.org. **Note:** To submit as a draft, use
-'git push origin HEAD:refs/drafts/master' Submitting as a draft means that
+`git push origin HEAD:refs/drafts/master`. Submitting as a draft means that
 your commit will be on coreboot.org, but is only visible to those you add
 as reviewers.
This has been a quick primer on how to submit a change to Gerrit for review
-using git.  You may wish to review the [Gerrit code review workflow
+using git. You may wish to review the [Gerrit code review workflow
 documentation](https://gerrit-review.googlesource.com/Documentation/intro-user.html#code-re...),
 especially if you plan to work on multiple changes at the same time.
## Part 4b: Using git cola to stage and submit a commit
If git cola is not installed on your machine, see
-https://git-cola.github.io/downloads.html for download instructions.
+https://git-cola.github.io/downloads.html for download instructions.
-After making some edits to src files, rather than run "git add," run
-'git cola' from the command line. You should see all of the files
+After making some edits to src files, rather than run `git add`, run
+`git cola` from the command line. You should see all of the files
 edited under "Modified".
In the textbox labeled "Commit summary" provide a brief one-line
 description of what you changed in the files according to the template
 below:
-`<filepath>: Short description`
-*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors*
+    <filepath>: Short description
+
+For example,
+
+    cpu/amd/pi/00630F01: Fix checkpatch warnings and errors
**Note:** It is good practice to use present tense in your descriptions
 and do not punctuate your short description.
In the larger text box labeled 'Extended description...' provide a more
 in-depth explanation of the changes you've made to the files. Again, it
-is good practice to use present tense.
-*ex.  Fix space prohibited between function name and open parenthesis,
-line over 80 characters, unnecessary braces for single statement blocks,
-space required before open brace errors and warnings.*
+is good practice to use present tense. Ex.
+
+    Fix space prohibited between function name and open parenthesis,
+    line over 80 characters, unnecessary braces for single statement blocks,
+    space required before open brace errors and warnings.
Then press Enter two times to move the cursor to below your description.
 To the left of the text boxes, there is an icon with an downward arrow.
 Press the arrow and select "Sign Off." Make sure that you are signing off
-with your name and email (i.e. **Your Name** **<Your Email>**, based on what
+with your name and email (i.e. **Your Name** **<Your Email>**, based on what
 you set with git config earlier).
Now, review each of your changes and mark either individual changes or
@@ -214,30 +222,30 @@
 explained in the extended description.
When ready, select 'Commit' again. Once all errors have been satisfied
-and the commit succeeds, move to the command line and run 'git push'.
-**Note:** To submit as a draft, use 'git push origin HEAD:refs/drafts/master'
+and the commit succeeds, move to the command line and run `git push`.
+**Note:** To submit as a draft, use `git push origin HEAD:refs/drafts/master`.
 Submitting as a draft means that your commit will be on coreboot.org, but is
 only visible to those you add as reviewers.
## Part 5: Getting your commit reviewed
-Your commits can now be seen on review.coreboot.org if you select “Your”
-and click on “Changes” and can be reviewed by others. Your code will
+Your commits can now be seen on review.coreboot.org if you select "Your"
+and click on "Changes" and can be reviewed by others. Your code will
 first be reviewed by build bot (Jenkins), which will either give you a warning
 or verify a successful build; if so, your commit will receive a +1. Other
-users may also give your commit +1.  For a commit to be merged, it needs
-to receive a +2.**Note:** A +1 and a +1 does not make a +2. Only certain users
+users may also give your commit +1. For a commit to be merged, it needs
+to receive a +2. **Note:** A +1 and a +1 does not make a +2. Only certain users
 can give a +2.
## Part 6 (optional): bash-git-prompt
To help make it easier to understand the state of the git repository
-without running 'git status' or 'git log', there is a way to make the
+without running `git status` or `git log`, there is a way to make the
 command line show the status of the repository at every point. This
 is through bash-git-prompt.
Instructions for installing this are found at:
-https://github.com/magicmonty/bash-git-prompt
+https://github.com/magicmonty/bash-git-prompt.
 **Note:** Feel free to search for different versions of git prompt,
 as this one is specific to bash.
@@ -250,7 +258,7 @@
 **Note:** cd will change your directory to your home directory, so the
 git clone command will be run there.
-Finally, open the ~/.bashrc file and append the following two lines:
+Finally, open the `~/.bashrc` file and append the following two lines:
GIT_PROMPT_ONLY_IN_REPO=1
     source ~/.bash-git-prompt/gitprompt.sh
@@ -260,7 +268,7 @@
There also are additional configurations that you can change depending on your
 preferences. If you wish to do so, look at the "All configs for .bashrc" section
-on https://github.com/magicmonty/bash-git-prompt. Listed in that section are
+on https://github.com/magicmonty/bash-git-prompt. Listed in that section are
 various lines that you can copy, uncomment and add to your .bashrc file to
 change the configurations. Example configurations include avoid fetching remote
 status, and supporting versions of Git older than 1.7.10.
@@ -273,7 +281,7 @@
 remote repository. If the commit you wish to update is the most recent
 commit you have made, after making your desired changes, stage the files
 (either using git add or in git cola), and amend the commit. To do so,
-if you are using the command line, run "git commit --amend." If you are
+if you are using the command line, run `git commit --amend`. If you are
 using git cola, click on the gear icon located on the upper left side under
 **Commit** and select **Amend Last Commit** in the drop down menu. Then, stage
 the files you have changed, commit the changes, and run git push to push the
-- 
To view, visit https://review.coreboot.org/c/coreboot/+/32804
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings

Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: I9931bef8c30387d1c08b59973d6de9b5c0419814
Gerrit-Change-Number: 32804
Gerrit-PatchSet: 1
Gerrit-Owner: Jacob Garber jgarber1@ualberta.ca
Gerrit-MessageType: newchange



    