1# OpenBMC Gerrit Setup/Integration 2 3**Document Purpose:** Walkthrough configuring your workstation and a Gerrit 4account. This is needed to participate in OpenBMC's Gerrit-based code reviews. 5 6**Prerequisites:** Current Linux, Mac, or Windows system. Git packages 7installed. E-mail account (recommended to use the same e-mail address for both 8Gerrit and GitHub). 9 10## Initial Setup 11 12##### Update Git Identity 13 14- `git config --global --add user.name "Your name" (eg. John Smith)` 15- `git config --global --add user.email "youremail@your-domain" (eg. jsmith@somedomain.com)` 16- (Optional) 17 `git config --global --add diff.tool "preferred diff tool" (eg. gvimdiff or meld)` 18 19##### Setup SSH Keys 20 21Create keys: `ssh-keygen -t ed25519 -C "your_email@your-domain"` 22 23- Recommended to use the defaults instead of picking your own directory/file 24 names. 25 26Add Keys to GitHub: 27 28- <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/> 29 30Add Keys to OpenBMC's Gerrit Server: 31 32- Login to [Gerrit](https://gerrit.openbmc.org/) with your GitHub account. 33- Go to <https://gerrit.openbmc.org/plugins/github-plugin/static/account.html> 34- Your information should be auto-filled, so click "Next". 35- If successful you should see a blank screen, feel free to exit out. 36 37**NOTE** If you receive a "Not found" error while trying to add the keys to 38Gerrit you can add them manually: 39 40- Login to [Gerrit](https://gerrit.openbmc.org/) 41- Enter your public SSH key created before in Settings -> SSH Keys -> New SSH 42 key 43- Click on "ADD NEW SSH KEY" 44- If succesfull you should see your public key added and with the status "Valid" 45 46##### Add e-mail to Gerrit 47 48- Login to [Gerrit](https://gerrit.openbmc.org/) 49- Enter e-mail in Settings -> Contact Information -> Register New E-Mail 50- Check e-mail for confirmation and click the link to confirm 51 52##### Add full name to Gerrit 53 54- Enter your full name in Settings -> Profile -> Full name 55 56##### Add SSH config entry 57 58Add the following to `~/.ssh/config`: 59 60``` 61Host openbmc.gerrit 62 Hostname gerrit.openbmc.org 63 Port 29418 64 User <Your Gerrit Username> 65``` 66 67- **NOTE**: There is a bug in AFS that requires `AFSTokenPassing no` to be added 68 to the SSH entry if using AFS. 69- Your Gerrit Username can be found in Gerrit under Settings -> Profile -> 70 Username 71- Ensure proper permissions for for your .ssh directory: `chmod 600 ~/.ssh/*` 72 73##### Confirm Setup Success 74 75Test connectivity to Gerrit by attempting to clone a repo 76 77- `git clone ssh://openbmc.gerrit/openbmc/docs` 78- If successful you should see something like: 79 `Checking out files: 100% (45/45), done.` 80 81##### Add Hooks 82 83Inside the repo you just cloned, enter the following commands: 84 85``` 86gitdir=$(git rev-parse --git-dir) 87curl https://gerrit.openbmc.org/tools/hooks/commit-msg -o ${gitdir}/hooks/commit-msg 88chmod +x ${gitdir}/hooks/commit-msg 89``` 90 91This will enhance the `git commit` command to add a `Change-Id` to your commit 92message which Gerrit uses to track the review. 93 94##### Push Code Change to Gerrit 95 96Now that your workstation and Gerrit are configured, you are ready to make code 97changes and push them to Gerrit for code review. Here is what the basic workflow 98will look like. 99 100- Make your code changes 101- Add those files to the index to be committed: 102 `git add [file1 file2 ... fileN]` 103- Commit your changes, adding a Signed-off-by line to it (more on 104 [writing good commit messages](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes)): 105 `git commit --signoff` 106- Push your changes to Gerrit for code review: 107 `git push origin HEAD:refs/for/master` 108- Go to [Gerrit web interface](https://gerrit.openbmc.org/), click on your new 109 review, and add reviewers based on `OWNERS` file in the repo. 110 111##### Conclusion 112 113If you've completed all of the above steps successfully, that's it! You have now 114set up Gerrit and know how to submit your code changes for review! 115 116Submitting changes for review is just one of many steps in the contributing 117process. Please see 118[CONTRIBUTING](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md) for 119best practices. 120