github.com/kchristidis/fabric@v1.0.4-0.20171028114726-837acd08cde1/docs/source/Gerrit/best-practices.rst (about) 1 Gerrit Recommended Practices 2 ============================ 3 4 This document presents some best practices to help you use Gerrit more 5 effectively. The intent is to show how content can be submitted easily. 6 Use the recommended practices to reduce your troubleshooting time and 7 improve participation in the community. 8 9 Browsing the Git Tree 10 --------------------- 11 12 Visit 13 `Gerrit <https://gerrit.hyperledger.org/r/#/admin/projects/fabric>`__ 14 then select ``Projects --> List --> SELECT-PROJECT --> Branches``. 15 Select the branch that interests you, click on ``gitweb`` located on the 16 right-hand side. Now, ``gitweb`` loads your selection on the Git web 17 interface and redirects appropriately. 18 19 Watching a Project 20 ------------------ 21 22 Visit 23 `Gerrit <https://gerrit.hyperledger.org/r/#/admin/projects/fabric>`__, 24 then select ``Settings``, located on the top right corner. Select 25 ``Watched Projects`` and then add any projects that interest you. 26 27 Commit Messages 28 --------------- 29 30 Gerrit follows the Git commit message format. Ensure the headers are at 31 the bottom and don't contain blank lines between one another. The 32 following example shows the format and content expected in a commit 33 message: 34 35 Brief (no more than 50 chars) one line description. 36 37 Elaborate summary of the changes made referencing why (motivation), what 38 was changed and how it was tested. Note also any changes to 39 documentation made to remain consistent with the code changes, wrapping 40 text at 72 chars/line. 41 42 | Jira: FAB-100 43 | Change-Id: LONGHEXHASH 44 | Signed-off-by: Your Name your.email\@example.org 45 | AnotherExampleHeader: An Example of another Value 46 47 The Gerrit server provides a precommit hook to autogenerate the 48 Change-Id which is one time use. 49 50 **Recommended reading:** `How to Write a Git Commit 51 Message <http://chris.beams.io/posts/git-commit/>`__ 52 53 Avoid Pushing Untested Work to a Gerrit Server 54 ---------------------------------------------- 55 56 To avoid pushing untested work to Gerrit. 57 58 Check your work at least three times before pushing your change to 59 Gerrit. Be mindful of what information you are publishing. 60 61 Keeping Track of Changes 62 ------------------------ 63 64 - Set Gerrit to send you emails: 65 66 - Gerrit will add you to the email distribution list for a change if a 67 developer adds you as a reviewer, or if you comment on a specific 68 Patch Set. 69 70 - Opening a change in Gerrit's review interface is a quick way to 71 follow that change. 72 73 - Watch projects in the Gerrit projects section at ``Gerrit``, select 74 at least *New Changes, New Patch Sets, All Comments* and *Submitted 75 Changes*. 76 77 Always track the projects you are working on; also see the 78 feedback/comments mailing list to learn and help others ramp up. 79 80 Topic branches 81 -------------- 82 83 Topic branches are temporary branches that you push to commit a set of 84 logically-grouped dependent commits: 85 86 To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed 87 as a topic in **TopicName** use the following command as an example: 88 89 $ git push REMOTE HEAD:refs/for/master/TopicName 90 91 The topic will show up in the review ``UI`` and in the 92 ``Open Changes List``. Topic branches will disappear from the master 93 tree when its content is merged. 94 95 Creating a Cover Letter for a Topic 96 ----------------------------------- 97 98 You may decide whether or not you'd like the cover letter to appear in 99 the history. 100 101 1. To make a cover letter that appears in the history, use this command: 102 103 :: 104 105 git commit --allow-empty 106 107 Edit the commit message, this message then becomes the cover letter. The 108 command used doesn't change any files in the source tree. 109 110 2. To make a cover letter that doesn't appear in the history follow 111 these steps: 112 113 - | Put the empty commit at the end of your commits list so it can be 114 ignored 115 | without having to rebase. 116 117 - Now add your commits 118 119 :: 120 121 git commit ... 122 git commit ... 123 git commit ... 124 125 - Finally, push the commits to a topic branch. The following command is 126 an example: 127 128 :: 129 130 git push REMOTE HEAD:refs/for/master/TopicName 131 132 If you already have commits but you want to set a cover letter, create 133 an empty commit for the cover letter and move the commit so it becomes 134 the last commit on the list. Use the following command as an example: 135 136 :: 137 138 git rebase -i HEAD~#Commits 139 140 Be careful to uncomment the commit before moving it. ``#Commits`` is the 141 sum of the commits plus your new cover letter. 142 143 Finding Available Topics 144 ------------------------ 145 146 :: 147 148 $ ssh -p 29418 gerrit.hyperledger.org gerrit query \ status:open project:fabric branch:master \ 149 | grep topic: | sort -u 150 151 - `gerrit.hyperledger.org <https://gerrit.hyperledger.org>`__ Is the current URL where the project is 152 hosted. 153 - *status* Indicates the topic's current status: open , merged, 154 abandoned, draft, merge conflict. 155 - *project* Refers to the current name of the project, in this case 156 fabric. 157 - *branch* The topic is searched at this branch. 158 - *topic* The name of an specific topic, leave it blank to include them 159 all. 160 - *sort* Sorts the found topics, in this case by update (-u). 161 162 Downloading or Checking Out a Change 163 ------------------------------------ 164 165 In the review UI, on the top right corner, the **Download** link 166 provides a list of commands and hyperlinks to checkout or download diffs 167 or files. 168 169 We recommend the use of the *git review* plugin. The steps to install 170 git review are beyond the scope of this document. Refer to the `git 171 review 172 documentation <https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers>`__ 173 for the installation process. 174 175 To check out a specific change using Git, the following command usually 176 works: 177 178 :: 179 180 git review -d CHANGEID 181 182 If you don't have Git-review installed, the following commands will do 183 the same thing: 184 185 :: 186 187 git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD 188 189 For example, for the 4th version of change 2464, NN is the first two 190 digits (24): 191 192 :: 193 194 git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD 195 196 Using Draft Branches 197 -------------------- 198 199 You can use draft branches to add specific reviewers before you 200 publishing your change. The Draft Branches are pushed to 201 ``refs/drafts/master/TopicName`` 202 203 The next command ensures a local branch is created: 204 205 :: 206 207 git checkout -b BRANCHNAME 208 209 The next command pushes your change to the drafts branch under 210 **TopicName**: 211 212 :: 213 214 git push REMOTE HEAD:refs/drafts/master/TopicName 215 216 Using Sandbox Branches 217 ---------------------- 218 219 You can create your own branches to develop features. The branches are 220 pushed to the ``refs/sandbox/USERNAME/BRANCHNAME`` location. 221 222 These commands ensure the branch is created in Gerrit's server. 223 224 :: 225 226 git checkout -b sandbox/USERNAME/BRANCHNAME 227 git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME 228 229 Usually, the process to create content is: 230 231 - develop the code, 232 - break the information into small commits, 233 - submit changes, 234 - apply feedback, 235 - rebase. 236 237 The next command pushes forcibly without review: 238 239 :: 240 241 git push REMOTE sandbox/USERNAME/BRANCHNAME 242 243 You can also push forcibly with review: 244 245 :: 246 247 git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME 248 249 Updating the Version of a Change 250 -------------------------------- 251 252 During the review process, you might be asked to update your change. It 253 is possible to submit multiple versions of the same change. Each version 254 of the change is called a patch set. 255 256 Always maintain the **Change-Id** that was assigned. For example, there 257 is a list of commits, **c0...c7**, which were submitted as a topic 258 branch: 259 260 :: 261 262 git log REMOTE/master..master 263 264 c0 265 ... 266 c7 267 268 git push REMOTE HEAD:refs/for/master/SOMETOPIC 269 270 After you get reviewers' feedback, there are changes in **c3** and 271 **c4** that must be fixed. If the fix requires rebasing, rebasing 272 changes the commit Ids, see the 273 `rebasing <http://git-scm.com/book/en/v2/Git-Branching-Rebasing>`__ 274 section for more information. However, you must keep the same Change-Id 275 and push the changes again: 276 277 :: 278 279 git push REMOTE HEAD:refs/for/master/SOMETOPIC 280 281 This new push creates a patches revision, your local history is then 282 cleared. However you can still access the history of your changes in 283 Gerrit on the ``review UI`` section, for each change. 284 285 It is also permitted to add more commits when pushing new versions. 286 287 Rebasing 288 -------- 289 290 Rebasing is usually the last step before pushing changes to Gerrit; this 291 allows you to make the necessary *Change-Ids*. The *Change-Ids* must be 292 kept the same. 293 294 - **squash:** mixes two or more commits into a single one. 295 - **reword:** changes the commit message. 296 - **edit:** changes the commit content. 297 - **reorder:** allows you to interchange the order of the commits. 298 - **rebase:** stacks the commits on top of the master. 299 300 Rebasing During a Pull 301 ---------------------- 302 303 Before pushing a rebase to your master, ensure that the history has a 304 consecutive order. 305 306 For example, your ``REMOTE/master`` has the list of commits from **a0** 307 to **a4**; Then, your changes **c0...c7** are on top of **a4**; thus: 308 309 :: 310 311 git log --oneline REMOTE/master..master 312 313 a0 314 a1 315 a2 316 a3 317 a4 318 c0 319 c1 320 ... 321 c7 322 323 If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull 324 with a rebase as follows: 325 326 :: 327 328 git pull --rebase REMOTE master 329 330 This pulls **a5-a7** and re-apply **c0-c7** on top of them: 331 332 :: 333 334 $ git log --oneline REMOTE/master..master 335 a0 336 ... 337 a7 338 c0 339 c1 340 ... 341 c7 342 343 Getting Better Logs from Git 344 ---------------------------- 345 346 Use these commands to change the configuration of Git in order to 347 produce better logs: 348 349 :: 350 351 git config log.abbrevCommit true 352 353 The command above sets the log to abbreviate the commits' hash. 354 355 :: 356 357 git config log.abbrev 5 358 359 The command above sets the abbreviation length to the last 5 characters 360 of the hash. 361 362 :: 363 364 git config format.pretty oneline 365 366 The command above avoids the insertion of an unnecessary line before the 367 Author line. 368 369 To make these configuration changes specifically for the current Git 370 user, you must add the path option ``--global`` to ``config`` as 371 follows: 372 373 .. Licensed under Creative Commons Attribution 4.0 International License 374 https://creativecommons.org/licenses/by/4.0/ 375