1. 1Copyright ©2012 CollabNet, Inc. All Rights Reserved. ENTERPRISE CLOUD DEVELOPMENT CollabNet TeamForge What’s Gerrit How to use Gerrit Code Review Feature with TeamForge as a Developer / Reviewer How to control Gerrit Code Review Policy on a TeamForge Repository Basis

2. 2Copyright ©2012 CollabNet, Inc. All Rights Reserved.2 1. What’s Gerrit

3. 3Copyright ©2012 CollabNet, Inc. All Rights Reserved. What is Gerrit Gerrit is a web based code review system, facilitating online code reviews for projects using the Git version control system. It also supports: Role-based access control Project scoping Source code repository provisioning (it acts as a Git server)

4. 4Copyright ©2012 CollabNet, Inc. All Rights Reserved. Gerrit Gerrit is deployed in place of the central repository and adds an additional concept, a store of pending changes. Everyone still fetches from the authoritative repository but instead of pushing back to it, they push to this pending changes location. Provides a framework for reviewing every commit before it is accepted into the code base. Changes are uploaded to Gerrit but don’t actually become a part of the project until they’ve been reviewed and accepted. A change can only be submitted into the authoritative repository and become an accepted part of the project once the change has been reviewed and approved. * Adopted from: http://gerrit.googlecode.com/git-history/7407a9236f32bd31697f5a9ff484145e080fc1b2/Documentation/images/intro-quick-central- gerrit.png Gerrit Workflow*

5. 5Copyright ©2012 CollabNet, Inc. All Rights Reserved.5 2. How to use Gerrit Code Review Feature with TeamForge as a Developer / Reviewer

6. 6Copyright ©2012 CollabNet, Inc. All Rights Reserved. Developer’s Actions Life Cycle of change(s) from Developer’s point of view Configuring local development environment Creating / Uploading SSH Keys to TeamForge STEP 1: Work with source code locally in Git and make changes Configuring Git with TeamForge user name and email address Checkout(clone) source code Make changes and commit them locally STEP 2 : Push changes for code review Push Changes to Gerrit for code review Rework changes if needed and push again for review

7. 7Copyright ©2012 CollabNet, Inc. All Rights Reserved. SSH public key Set up the SSH Public Key. Each user uploading changes to Gerrit must configure one or more SSH public keys. This key allows a secure connection between the host client and Gerrit. 1. To set up your SSH Public Key follow these steps: Check whether SSH keys are already there. If not, generate new ssh key pair

8. 8Copyright ©2012 CollabNet, Inc. All Rights Reserved. SSH public key 2. Copy your public ssh key from the id_rsa.pub file content into clipboard Enter ‘cat ~/.ssh/id_rsa.pub’ Copy the displayed content 1 2

9. 9Copyright ©2012 CollabNet, Inc. All Rights Reserved. SSH public key 3. Paste it on the Authorization Keys field in TeamForge Paste your SSH key into the text box 1 Click Update 5 Go to My Workspace Choose My Settings Choose My Settings 2 4 Select the Authorization Keys tab 3 Once your SSH key is uploaded on TeamForge it is automatically sent to Gerrit. TeamForge does not validate what you type there, so it is important to copy the key exactly without adding newlines or whitespace.

10. 10Copyright ©2012 CollabNet, Inc. All Rights Reserved. Check out or clone the central repository that Gerrit is hosting. The lifecycle of a change The first thing Robin needs to do is: Get the source code and make changes. To do so he follows these steps: 1 Click Source Code 2 Click on the repository you are interested in User ‘Robin’ clones the repository and makes changes 1. Checking out code

11. 11Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change 3 Copy the Checkout Command into clipboard 4 Paste it into the command-line interface (clone Git repository)

12. 12Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change Configure user name and email for Git repository (registered with Teamforge) You could also configure username / email for all Git repositories by using git config --global user.name “robin” git config --global user.email “robin@collab.net” 2. Configure Git

13. 13Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change Now it’s time to make the changes to the source code and commit them locally entering ‘git add’ and ‘ git commit’ commands into the command-line interface (CLI). 1 2 s Checking status shows clean repository Fetching changes from remote ‘master’ & creating local ‘feature branch’ Doing changes (modifying file) 3 4 Adding file under version control Checking branch When working with changes from Gerrit, it is advisable to create local branch ( git checkout –b ) and then start working on that branch 3. Changing code

14. 14Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change 4. Commit, Rebase & Push changes for code review to Gerrit HEAD:refs/for/master indicates that changes will be pushed for review on branch master(remote) 7 Rebase will basically stacks up last commit on top latest from ‘remote’ (master) 8 Changes are pushed for review in Gerrit

15. 15Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change User ‘Robin – the Developer’ can go to Gerrit WebUI by pressing ‘Gerrit’ tab in TeamForge and see recently placed reviews Commit which has been pushed, appears on Gerrit UI with unique change ID. Every member who has access to this project can also see this review request when they visit Gerrit WebUI (i.e ‘David –the –reviewer‘ can see this review request )

16. 16Copyright ©2012 CollabNet, Inc. All Rights Reserved. Reviewer’s Actions STEP 1: Observing review Request On Gerrit WebUI Reviewer can see all review requests sent by developers Select review interested in STEP 2: Review Evaluate changes done in side-by-side or unified diff view and place inline comment ‘Checkout’ locally changes under review STEP 3 : Take decision Place opinion by commenting Add other user(s) as reviewer Take decision Accept Change Reject Change Accept & Submit change to ‘blessed repository’ Life Cycle of change(s) from Reviewer’s point of view

17. 17Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change User ‘David-the Reviewer’ can go to Gerrit WebUI by pressing ‘Gerrit’ tab in TeamForge and see review request from ‘Robin-the Developer’ As David has “Reviewer role ” in TeamForge, he can review this request and place his opinion by clicking this change ID

18. 18Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change If David already has a local version of a repository and wants to work over a change Robin (or others) has pushed, he can just download the change and work on it locally. Alternatively he can view changes side- by-side. Copy the Git fetch command on your command- line interface and review in workspace locally Developers can fetch and checkout a branch from Gerrit collaborating in one patch before committing to the master branch 1 Click Diff All Side-by-side to review commit on Gerrit web UI 1 - Or- 5. Reviewing Changes

19. 19Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change Comments can be added by double clicking on a line (or single clicking the line number). Once published these comments are viewable to all, allowing discussion of the change to take place. Diff side-by-side view

20. 20Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change Invite user to review*. *It isn’t mandatory that added reviewer must give his vote for this review.Without invited user review can pass once it’s able garner enough votes David / Robin can also designate who can review Robin’s commit on the Gerrit web interface in TeamForge. 2

21. 21Copyright ©2012 CollabNet, Inc. All Rights Reserved. Gerrit has keyboard shortcuts for most operations during review. The ? key displays keyboard shortcuts. The lifecycle of a change

22. 22Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change 1 Once you have looked over the changes complete reviewing the submission by scoring it. To do this follow these steps: Click Review 6. Finalizing Code Review

23. 23Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change 2 3 Evaluate if the code compiles Evaluate if the code compiles, if so rate +1, if not -1. Usually this is done by an automated build server rather than a person, still you can do it manually. Look at the code Look at the code, ensuring it meets the project guidelines, intent etc. If you have the corresponding permission you can rate it from +2 to -2 NOTE: Only TeamForge User having a role with Delete/Commit view –- or - SCM Admin source code permission can see +2 to -2 range and ‘submit’ button, all other user will see -1 to +1 range while doing review and they won’t see ‘submit’ button 4 Enter a comment and click Publish Comments Enter a comment and click Publish Comments. This way any comments on the files become visible to all users.

24. 24Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change +1 and -1 level are just an opinion, reviewers rate +1 if a change is ready to be submitted and -1 if still needs work. Whereas the +2 and -2 levels are allowing or blocking the change. In order for a change to be accepted and the commit get merged it must have at least one +2 and no -2 votes. (David-the Reviewer has this right as he has role with Delete/View permission in TeamForge) Code Review These are numeric values, but not accumulative; two +1s do not equate to a +2.

25. 25Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change 1 Copy the Change-Id If the ‘David the reviewer’ rates change negatively and not verified, ‘Robin- the Developer’ has to rework it. To upload the new version of an existing review request follow these steps: Gerrit Code Review provides a standard commit-msg hook which can be installed in the local Git repository to automatically create and insert a unique Change-Id line during git commit. So when reworking a change it associates the new version back to the original review. In this case all you need to do is to checkout and then amend the commit. To get hoosks into your local Git repositoy run $ scp -p -P 29418 @ :hooks/commit-msg.git/hooks 7. Reworking on a change after review

26. 26Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change 2 Type ‘git commit --amend’ in the command-line interface C ommit names and Change- Ids are not the same. To avoid confusion remember that Change-Ids typically start with an uppercase. Once you save commit message, commit will be amended 4 3 Rework the change, edit commit message (if needed) and refer to Change-Id (in case you don’t have commit hooks)

27. 27Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change 5 Finally, push the new version to Gerrit, in the same way as before

28. 28Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change Afterwards ‘David –the Reviewer ’ will find on the Gerrit webUI two patch sets which correspond to the different versions 6 Reworked commit pushed again for review.

29. 29Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change To submit a change click the Publish and Submit button Just as Code Review and Verify are different operations that can be done by different users, Submission is a third operation that can be limited down to another group of users. If the patch is verified and given a +2 score by ‘David –the Reviewer ’, it is ready to be submitted, this means the change will be merged into the main part of the repository so that it becomes an accepted part of the project. 8. Submitting the change

30. 30Copyright ©2012 CollabNet, Inc. All Rights Reserved. 1 Select category 2 Type in group internal group name 3 Select permitted range

31. 31Copyright ©2012 CollabNet, Inc. All Rights Reserved. The lifecycle of a change Just as Code Review and Verify are different operations that can be done by different users, Submission is a third operation that can be limited down to another group of users. If the patch is verified and given a +2 score by ‘David –the Reviewer ’, it is ready to be submitted, this means the change will be merged into the After submit, Commit will appear in TeamForge Commit details with commit message 9. Change appears in TeamForge

32. 32Copyright ©2012 CollabNet, Inc. All Rights Reserved.32Copyright ©2012 CollabNet, Inc. All Rights Reserved. 3. How to control Gerrit Code Review Policy on a TeamForge Repository Basis

33. 33Copyright ©2012 CollabNet, Inc. All Rights Reserved. TeamForge Project Admin’s Actions STEP 1: Creating / Update Git Repository Creating / Updating repository in TeamForge STEP 2: Control Git Repository Turn ON Code Review (Either Enforce or impose it Optionally) Turn Code Review OFF STEP 3 : Manage Code Review Process Create /update role & assign to users Who can review Who can read source code / submit review code review Who can bypass code review

34. 34Copyright ©2012 CollabNet, Inc. All Rights Reserved. TeamForge Project Admin To enforce code review put a string “[RepoCategory:mandatory_review]” as a part of the description field STEP 1 & 2: Creating /Updating a Git repository and configuring it with mandatory Gerrit Code Review 1 2 3 Select ‘Git’ as server Make sure that you have “[RepoCategory:mandatory_review]” in description field Press save button If Code Review process is mandatory then every single changes submitted to ‘blessed Git Repository’ in TeamForge has to get reviewed and accepted in Gerrit.

35. 35Copyright ©2012 CollabNet, Inc. All Rights Reserved. TeamForge Project Admin To enforce code review secte“[RepoCategory:mandatory_review]” as a part of the description field STEP 1 & 2: Creating /Updating a Git repository and configuring it with mandatory Gerrit Code Review in TeamForge 7.0 1 2 Select ‘Git’ as server Make sure that you have “Mandatory review” selected If Code Review process is mandatory then every single changes submitted to ‘blessed Git Repository’ in TeamForge has to get reviewed and accepted in Gerrit.

36. 36Copyright ©2012 CollabNet, Inc. All Rights Reserved. TeamForge Project Admin STEP 3.1: Create/Update a role for developer with view only permission 1 2 Press save button Select ‘View only’

37. 37Copyright ©2012 CollabNet, Inc. All Rights Reserved. TeamForge Project Admin STEP 3.2: Create a role for reviewer with “delete/view “ or “commit/view” permissions 1 2 Press save button Select ‘Delete / View’ 1 Select ‘Commit / View’ - or -

38. 38Copyright ©2012 CollabNet, Inc. All Rights Reserved. TeamForge Project Admin STEP 3.3: Assign corresponding roles (reviewer/developer) to the project members Developer can: checkout(clone, fetch) source code create local changes and push them for “review” in Gerrit participate in code review process without final decision privileges Reviewer can: checkout(clone, fetch) source code create local changes and push them for “review” in Gerrit participate in code review process & with final decision privileges (submit or reject)

39. 39Copyright ©2012 CollabNet, Inc. All Rights Reserved. TeamForge Project Admin To have optional code review put a string “[RepoCategory:optional_review]” as a part of the descritpion field Creating /Updating a Git repository and configuring it with optional Code Review 1 Make sure that you have “[RepoCategory:optional_review]” in description field If Code Review process is optionally then every single changes submitted to ‘blessed Git Repository’ in TeamForge can be pushed for code review or it can be pushed to ‘blessed repository’ directly, bypassing review, when TF user has role with appropriate permissions

40. 40Copyright ©2012 CollabNet, Inc. All Rights Reserved. TeamForge Project Admin To have optional code review selected from list of code review policies Creating /Updating a Git repository and configuring it with optional Code Review in TeamForge 7.0 1 Make sure that you have “Optional Review ” selected If Code Review process is optionally then every single changes submitted to ‘blessed Git Repository’ in TeamForge can be pushed for code review or it can be pushed to ‘blessed repository’ directly, bypassing review, when TF user has role with appropriate permissions

41. 41Copyright ©2012 CollabNet, Inc. All Rights Reserved. Permission for “Developer role” Permissions for “Reviewer role” TeamForge Project Admin Setting up Project Roles in TeamForge When Gerrit Code Review is set Optional Select ‘ Commit/View’ 1 1 Select both ‘’Delete/View & Commit/View Developer can: checkout(clone, fetch) source code create local changes and push them for “review” in Gerrit participate in code review process with final decision privileges (submit or reject) directly push changes to ‘blessed repository’, bypassing review Reviewer can: checkout(clone, fetch) source code create local changes and push them for “review” in Gerrit participate in code review process with final decision privileges (submit or reject) directly push changes to ‘blessed repository’, bypassing review

42. 42Copyright ©2012 CollabNet, Inc. All Rights Reserved. TeamForge Project Admin Turning Gerrit Code Review Off (Default) in TeamForge 6.2.x 1 Make sure that your repository description does not/no longer contain “[RepoCategory:optional_review]” or “[RepoCategory:mandatory_review]” When code review feature is turned off, TeamForge RBAC source code permissions will not result in code review related access rights in Gerrit. Source code access will still be enforced.

43. 43Copyright ©2012 CollabNet, Inc. All Rights Reserved. TeamForge Project Admin Turning Gerrit Code Review Off (Default) with TeamForge 7.0 1 In TeamForge 7.0 Repository Category «Default-no review» should be selected When code review feature is turned off, TeamForge RBAC source code permissions will not result in code review related access rights in Gerrit. Source code access will still be enforced.

44. 44Copyright ©2012 CollabNet, Inc. All Rights Reserved. In addition to mandatory review, optional review and review turned off (default), advanced project admins can – define their own review policies and tailor them to their company specific requirements by adding new SCM categories in gerritforge.mappings (requires access to this file) – use keyword [RepoCategory:custom] which enables setting different Gerrit access rights per TF project role. In this case, access rights have to be set in Gerrit’s Web UI directly and will not be overridden by TeamForge. Only TF members with SCM admin permissions will be able to do so. More details on both options can be found on hcn and our README TeamForge Project Admin / Advanced Topics

45. 45Copyright ©2012 CollabNet, Inc. All Rights Reserved.45Copyright ©2012 CollabNet, Inc. All Rights Reserved. About CollabNet CollabNet is a leading provider of Enterprise Cloud Development and Agile ALM products and services for software-driven organizations. With more than 10,000 global customers, the company provides a suite of platforms and services to address three major trends disrupting the software industry: Agile, DevOps and hybrid cloud development. Its CloudForge ™ development-Platform-as-a-Service (dPaaS) enables cloud development through a flexible platform that is team friendly, enterprise ready and integrated to support leading third party tools. The CollabNet TeamForge ® ALM, ScrumWorks ® Pro project management and SubversionEdge source code management platforms can be deployed separately or together, in the cloud or on-premise. CollabNet complements its technical offerings with industry leading consulting and training services for Agile and cloud development transformations. Many CollabNet customers improve productivity by as much as 70 percent, while reducing costs by 80 percent. For more information, please visit www.collab.net.www.collab.net

46. 46Copyright ©2012 CollabNet, Inc. All Rights Reserved.46Copyright ©2012 CollabNet, Inc. All Rights Reserved. © 2012 CollabNet, Inc., All rights reserved. CollabNet is a trademark or registered trademark of CollabNet Inc., in the US and other countries. All other trademarks, brand names, or product names belong to their respective holders. CollabNet, Inc. 8000 Marina Blvd., Suite 600 Brisbane, CA 94005 www.collab.net +1-650-228-2500 +1-888-778-9793 blogs.collab.net twitter.com/collabnet www.facebook.com/collabnet www.linkedin.com/company/collabnet-inc