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##### Add e-mail to Gerrit 38 39- Login to [Gerrit](https://gerrit.openbmc.org/) 40- Enter e-mail in Settings -> Contact Information -> Register New E-Mail 41- Check e-mail for confirmation and click the link to confirm 42 43##### Add full name to Gerrit 44 45- Enter your full name in Settings -> Profile -> Full name 46 47##### Add SSH config entry 48 49Add the following to `~/.ssh/config`: 50 51``` 52Host openbmc.gerrit 53 Hostname gerrit.openbmc.org 54 Port 29418 55 User <Your Gerrit Username> 56``` 57 58- **NOTE**: There is a bug in AFS that requires `AFSTokenPassing no` to be added 59 to the SSH entry if using AFS. 60- Your Gerrit Username can be found in Gerrit under Settings -> Profile -> 61 Username 62- Ensure proper permissions for for your .ssh directory: `chmod 600 ~/.ssh/*` 63 64##### Confirm Setup Success 65 66Test connectivity to Gerrit by attempting to clone a repo 67 68- `git clone ssh://openbmc.gerrit/openbmc/docs` 69- If successful you should see something like: 70 `Checking out files: 100% (45/45), done.` 71 72##### Add Hooks 73 74Inside the repo you just cloned, enter the following commands: 75 76``` 77gitdir=$(git rev-parse --git-dir) 78scp -p -P 29418 openbmc.gerrit:hooks/commit-msg ${gitdir}/hooks 79``` 80 81This will enhance the `git commit` command to add a `Change-Id` to your commit 82message which Gerrit uses to track the review. 83 84##### Push Code Change to Gerrit 85 86Now that your workstation and Gerrit are configured, you are ready to make code 87changes and push them to Gerrit for code review. Here is what the basic workflow 88will look like. 89 90- Make your code changes 91- Add those files to the index to be committed: 92 `git add [file1 file2 ... fileN]` 93- Commit your changes, adding a Signed-off-by line to it (more on 94 [writing good commit messages](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes)): 95 `git commit --signoff` 96- Push your changes to Gerrit for code review: 97 `git push origin HEAD:refs/for/master` 98- Go to [Gerrit web interface](https://gerrit.openbmc.org/), click on your new 99 review, and add reviewers based on `OWNERS` file in the repo. 100 101##### Conclusion 102 103If you've completed all of the above steps successfully, that's it! You have now 104set up Gerrit and know how to submit your code changes for review! 105 106Submitting changes for review is just one of many steps in the contributing 107process. Please see 108[CONTRIBUTING](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md) for 109best practices. 110