part2.md
1 # Tutorial, part 2: Submitting a patch to coreboot.org 2 3 ## Step 1: Set up an account at coreboot.org 4 5 If you already have an account, skip to Step 2. 6 7 Otherwise, go to <https://review.coreboot.org> in your preferred web 8 browser. Select **Sign in** in the upper right corner. 9 10 Select the appropriate sign-in. For example, if you have a Google 11 account, select **Google OAuth2** (gerrit-oauth-provider plugin). 12 **Note:** Your username for the account will be the username of the 13 account you used to sign-in with. (ex. your Google username). 14 15 ## Step 2a: Set up SSH keys 16 17 If you prefer to use an HTTP password instead, skip to Step 2b. 18 19 If you do not have an SSH key set up on your account already (as is the 20 case with a newly created account), follow the instructions below; 21 otherwise, doing so could overwrite an existing key. 22 23 In a terminal, run `ssh-keygen -t ed25519` and confirm the default path 24 `.ssh/id_ed25519`. 25 26 Make a passphrase -- remember this phrase. It will be needed whenever 27 you use this public key. **Note:** You might want to use a short 28 password, or forego the password altogether as you will be using it very 29 often. 30 31 Copy the content of `.ssh/id_ed25519.pub` (notice the ".pub" suffix 32 as you need to send the public key) into the textbox "New SSH Key" at 33 <https://review.coreboot.org/settings/#SSHKeys> and save it. 34 35 ## Step 2b: Set up an HTTP Password 36 37 Alternatively, instead of using SSH keys, you can use an HTTP password. 38 To do so, after you select your name and click on **Settings** on the 39 left-hand side, rather than selecting **SSH Public Keys**, select **HTTP 40 Password**. 41 42 Click **Generate Password**. This should fill the "Password" box with a 43 password. Copy the password, and add the following to your 44 `$HOME/.netrc` file: 45 46 machine review.coreboot.org login YourUserNameHere password YourPasswordHere 47 48 where YourUserNameHere is your username, and YourPasswordHere is the 49 password you just generated. 50 51 If your system is behind a snooping HTTPS proxy, you might also have to 52 make its SSL certificate known to curl, a system specific operation. 53 If that's not possible for some reason, you can also disable SSL 54 certificate verification in git: 55 56 git config [--global] http.sslVerify [true|false] 57 58 The `--global` argument sets it for all git transfers of your local 59 user, `false` means not to validate the certificate. 60 61 If that still doesn't allow you to pull or push changes to the server, 62 the proxy is likely tampering with the data stream, in which case 63 there's nothing we can do. 64 65 ## Step 3: Clone coreboot and configure it for submitting patches 66 67 On Gerrit, click on the **Browse** tab in the upper left corner and 68 select **Repositories**. From the listing, select the "coreboot" repo. 69 You may have to click the next page arrow at the bottom a few times to 70 find it. 71 72 If you are using SSH keys, select **ssh** from the tabs under "Project 73 coreboot" and run the "clone with commit-msg hook" command that's 74 provided. This should prompt you for your id_rsa passphrase, if you 75 previously set one. 76 77 **Note:** if the **ssh** option is not showing, check that you have a 78 username set. Click the profile picture at the top right and select 79 **User Settings**, then set your username in the **Profile** section. 80 81 If you are using HTTP, instead, select **http** from the tabs under 82 "Project coreboot" and run the command that appears. 83 84 Now is a good time to configure your global git identity, if you haven't 85 already. 86 87 git config --global user.name "Your Name" 88 git config --global user.email "Your Email" 89 90 Finally, enter the local git repository and set up repository specific 91 hooks and other configurations. 92 93 cd coreboot 94 make gitconfig 95 96 ## Step 4: Submit a commit 97 98 An easy first commit to make is fixing existing checkpatch errors and 99 warnings in the source files. To see errors that are already present, 100 build the files in the repository by running `make lint` in the coreboot 101 directory. Alternatively, if you want to run `make lint` on a specific 102 directory, run: 103 104 util/lint/lint-007-checkpatch <filepath> 105 106 where `filepath` is the filepath of the directory (ex. 107 `src/cpu/amd/car`). 108 109 Any changes made to files under the src directory are made locally, 110 and can be submitted for review. 111 112 Once you finish making your desired changes, use the command line to 113 stage and submit your changes. An alternative and potentially easier way 114 to stage and submit commits is to use git cola, a graphical user 115 interface for git. For instructions on how to do so, skip to Step 4b. 116 117 ## Step 4a: Use the command line to stage and submit a commit 118 119 To use the command line to stage a commit, run 120 121 git add <filename> 122 123 where `filename` is the name of your file. 124 125 To commit the change, run 126 127 git commit -s 128 129 **Note:** The -s adds a signed-off-by line by the committer. Your commit 130 should be signed off with your name and email (i.e. **Your Name** 131 **\<Your Email\>**, based on what you set with git config earlier). 132 133 Running git commit first checks for any errors and warnings using lint. 134 If there are any, you must go back and fix them before submitting your 135 commit. You can do so by making the necessary changes, and then staging 136 your commit again. 137 138 When there are no errors or warnings, your default text editor will 139 open. This is where you will write your commit message. 140 141 The first line of your commit message is your commit summary. This is a 142 brief one-line description of what you changed in the files using the 143 template below: 144 145 <filepath>: Short description 146 147 For example, 148 149 cpu/amd/pi/00630F01: Fix checkpatch warnings and errors 150 151 **Note:** It is good practice to use present tense in your descriptions 152 and do not punctuate your summary. 153 154 Then hit Enter. The next paragraph should be a more in-depth explanation 155 of the changes you've made to the files. Again, it is good practice to 156 use present tense. Ex. 157 158 Fix space prohibited between function name and open parenthesis, 159 line over 80 characters, unnecessary braces for single statement 160 blocks, space required before open brace errors and warnings. 161 162 When you have finished writing your commit message, save and exit the 163 text editor. You have finished committing your change. If, after 164 submitting your commit, you wish to make changes to it, running `git 165 commit --amend` allows you to take back your commit and amend it. 166 167 When you are done with your commit, run `git push` to push your commit 168 to coreboot.org. **Note:** To submit as a private patch, use `git push 169 origin HEAD:refs/for/main%private`. Submitting as a private patch 170 means that your commit will be on review.coreboot.org, but is only 171 visible to yourself and those you add as reviewers. This mode isn't 172 perfect: Somebody who knows the commit ID can still fetch the change and 173 everything it refers (e.g. parent commits). 174 175 This has been a quick primer on how to submit a change to Gerrit for 176 review using git. You may wish to review the [Gerrit code review 177 workflow 178 documentation](https://gerrit-review.googlesource.com/Documentation/intro-user.html#code-review), 179 especially if you plan to work on multiple changes at the same time. 180 181 ## Step 4b: Use git cola to stage and submit a commit 182 183 If git cola is not installed on your machine, see 184 <https://git-cola.github.io/downloads.html> for download instructions. 185 186 After making some edits to src files, rather than run `git add`, run 187 `git cola` from the command line. You should see all of the files 188 edited under "Modified". 189 190 In the textbox labeled "Commit summary" provide a brief one-line 191 description of what you changed in the files according to the template 192 below: 193 194 <filepath>: Short description 195 196 For example, 197 198 cpu/amd/pi/00630F01: Fix checkpatch warnings and errors 199 200 **Note:** It is good practice to use present tense in your descriptions 201 and do not punctuate your short description. 202 203 In the larger text box labeled 'Extended description...' provide a more 204 in-depth explanation of the changes you've made to the files. Again, it 205 is good practice to use present tense. Ex. 206 207 Fix space prohibited between function name and open parenthesis, 208 line over 80 characters, unnecessary braces for single statement 209 blocks, space required before open brace errors and warnings. 210 211 Then press Enter two times to move the cursor to below your description. 212 To the left of the text boxes, there is an icon with an downward arrow. 213 Press the arrow and select "Sign Off." Make sure that you are signing 214 off with your name and email (i.e. **Your Name** **\<Your Email\>**, 215 based on what you set with git config earlier). 216 217 Now, review each of your changes and mark either individual changes or 218 an entire file as Ready to Commit by marking it as 'Staged'. To do 219 this, select one file from the 'Modified' list. If you only want to 220 submit particular changes from each file, then highlight the red and 221 green lines for your changes, right click and select 'Stage Selected 222 Lines'. Alternatively, if an entire file is ready to be committed, just 223 double click on the file under 'Modified' and it will be marked as 224 Staged. 225 226 Once the descriptions are done and all the edits you would like to 227 commit have been staged, press 'Commit' on the right of the text 228 boxes. 229 230 If the commit fails due to persisting errors, a text box will appear 231 showing the errors. You can correct these errors within 'git cola' by 232 right-clicking on the file in which the error occurred and selecting 233 'Launch Diff Tool'. Make necessary corrections, close the Diff Tool and 234 'Stage' the corrected file again. It might be necessary to refresh 235 'git cola' in order for the file to be shown under 'Modified' again. 236 Note: Be sure to add any other changes that haven't already been 237 explained in the extended description. 238 239 When ready, select 'Commit' again. Once all errors have been satisfied 240 and the commit succeeds, move to the command line and run `git push`. 241 242 ## Step 5: Let others review your commit 243 244 Your commits can now be seen on review.coreboot.org if you select "Your" 245 and click on "Changes" and can be reviewed by others. Your code will 246 first be reviewed by build bot (Jenkins), which will either give you a 247 warning or verify a successful build; if so, your commit will receive a 248 +1. Other users may also give your commit +1. For a commit to be merged, 249 it needs to receive a +2. **Note:** A +1 and a +1 does not make a +2. 250 Only certain users can give a +2. 251 252 ## Step 6 (optional): bash-git-prompt 253 254 To help make it easier to understand the state of the git repository 255 without running `git status` or `git log`, there is a way to make the 256 command line show the status of the repository at every point. This 257 is through bash-git-prompt. 258 259 Instructions for installing this are found at: 260 <https://github.com/magicmonty/bash-git-prompt>. 261 **Note:** Feel free to search for different versions of git prompt, 262 as this one is specific to bash. 263 264 Alternatively, follow the instructions below: 265 Run the following two commands in the command line: 266 267 ```Bash 268 cd 269 git clone https://github.com/magicmonty/bash-git-prompt.git \ 270 .bash-git-prompt --depth=1 271 ``` 272 **Note:** cd will change your directory to your home directory, so the 273 git clone command will be run there. 274 275 Finally, open the `~/.bashrc` file and append the following two lines: 276 277 GIT_PROMPT_ONLY_IN_REPO=1 278 source ~/.bash-git-prompt/gitprompt.sh 279 280 Now, whenever you are in a git repository, it will continuously display 281 its state. 282 283 There also are additional configurations that you can change depending 284 on your preferences. If you wish to do so, look at the "All configs for 285 .bashrc" section on <https://github.com/magicmonty/bash-git-prompt>. 286 Listed in that section are various lines that you can copy, uncomment 287 and add to your .bashrc file to change the configurations. Example 288 configurations include avoid fetching remote status, and supporting 289 versions of Git older than 1.7.10. 290 291 ## Appendix: Miscellaneous Advice 292 293 ### Updating a commit after running git push: 294 295 Suppose you would like to update a commit that has already been pushed 296 to the remote repository. If the commit you wish to update is the most 297 recent commit you have made, after making your desired changes, stage 298 the files (either using git add or in git cola), and amend the commit. 299 To do so, if you are using the command line, run `git commit --amend`. 300 If you are using git cola, click on the gear icon located on the upper 301 left side under **Commit** and select **Amend Last Commit** in the drop 302 down menu. Then, stage the files you have changed, commit the changes, 303 and run git push to push the changes to the remote repository. Your 304 change should be reflected in Gerrit as a new patch set. 305 306 If, however, the commit you wish to update is not the most recent commit 307 you have made, you will first need to checkout that commit. To do so, 308 find the URL of the commit on <https://review.coreboot.org> and go to 309 that page; if the commit is one that you previously pushed, it can be 310 found by selecting **My** and then **Changes** in the upper left corner. 311 To checkout this commit, in the upper right corner, click on 312 **Download**, and copy the command listed next to checkout by clicking 313 **Copy to clipboard**. Then, run the copied command in your coreboot 314 repository. Now, the last commit should be the most recent commit to 315 that patch; to update it, make your desired changes, stage the files, 316 then amend and push the commit using the instructions in the above 317 paragraph.