Migration To Git

Recommended Reading

• Gerrit introduction: https://gerrit-review.googlesource.com/Documentation/intro-quick.html.

Gerrit

1. Request a Gerrit account. If your already have a SVN account, it should work also in Gerrit.
2. Generate SSH Public/Private key
   • Windows
     • Install PuTTY (msi) or download only PuTTYgen (exe) (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
     • Run PuTTYgen and generate a key
       • Press Generate button
       • Move your mouse over the window until the progress bar is finished
       • Write a Key passphrase to protect your private key in case your local machine is compromised.
       • Save the generated public and private keys to C:\Users\{username}\.ssh.
   • Linux
     • Generate public and private keys using ssh-keygen.
3. Go to http://www.simantics.org:8088/r/ and log in with your Gerrit username/password
4. Select your name in the top-right corner and press Settings
5. Go to section SSH Public Keys, select Add Key ....
6. Open the file containing the generated public key in text editor and paste its content to the box in Gerrit and and press Add

Eclipse

The following instructions are written for Eclipse Neon. There might be some differences if you are using Mars.

1. Go to preferences (General / Network Connections / SSH2) and ensure that SSH2 home points to the directory where you saved the private key.
2. Open Git perspective
3. Press button Clone a Git Repository and add the clone to this view (third button in the toolbar of Git view)
4. Select Clone URI (Don't select Gerrit, it doesn't work very well at the moment)
5. Go back to Gerrit. Press Projects in the top-left menu and List in the submenu.
6. Find a row named simantics/platform and press (gitweb) link at the last column.
7. Copy the URI starting with ssh: (ssh://{username}@www.simantics.org:29418/simantics/platform.git) and paste it to URI field in Clone Git Repository dialog.
8. This should automatically fill the other fields.
9. Press Next. If your private key has a passphrase, Eclipse now asks it.
10. Select all branches to be cloned (default) and press Next.
11. Give a local directory where the repository is cloned to and press Finish.
12. After the cloning is finished, select the platform repository in the Git Repositories view and select Import Projects... from context menu.
13. Press Next, select all projects but org.simantics.root and press Finish.
14. Expand the tree view of platform, expand Branches under it and Local under it. Open context menu on master branch and select Configure Branch.... Select Rebase checkbox.

Updating your local repository and working space

1. Open context menu on platform in the Git perspective and select Pull.

Committing your changes back to shared repository

1. Select platform in the Git perspective and open Git Staging view.
2. Unstaged Changes shows all files you have modified.
3. Drag&drop those changes you want to commit to the box Staged Changes.
4. Write a commit message
5. Ensure that Add Change-Id button is toggled down and the commit message contains a row starting Change-Id:.
   • This is required by Gerrit to be able to bind commits to specific reviews. Gerrit will replace the default zero-valued Id with a generated one when the change is pushed for review.
6. Press Commit and Push...
7. This opens a dialog that asks the Gerrit Branch and a Topic. Topic can be added optionally to tie multiple changes together.
   • Example of a topic: http://www.simantics.org:8088/r/#/q/topic:svn
8. Go to Gerrit. In the top-left menu select My and select Changes.
9. Your change can be seen now in the section Outgoing reviews.
10. Click the change. This opens a review page.
11. Ask someone to review your change. This can be done also in Gerrit by pressing Add... button in the right of the Reviewers field.
12. If you need to make modifications to your changes based on reviews, you'll need to Amend the earlier changes to send a new patch set to Gerrit. In this case, ensure that the Amend (Edit Previous Commit) button is toggled down and you should be able to modify the earlier commit message and push the amended changes.
13. When somebody has reviewed and accepted the change with +2, the review page will contain a Submit button that can be used to merge the change to the master branch.

Commit message format

In Git, the first row of the commit message is used for shortlog and generating patch file names so keep it short, concise and descriptive as possible. The commit box in the UI shows a vertical line marking the maximum length of a commit message line and the view will inform you if you're exceeding limits.

To keep commits attached to Redmine issues, use refs #nnn, where nnn is the issue number. This must be specified before Change-Id:'.

Gerrit reviews require a row starting Change-Id: as the last row of the commit message (excluding Signed-off-by rows). This allows Gerrit to bind commits to specific reviews. Gerrit will replace the default zero-valued Id with a generated one when the change is pushed for review.

All in all, a typical commit message should look like this:

Short description of my change
 
A longer description of my changes
that can span multiple lines.
 
refs #nnn

Change-Id: I0000000000000000000000000000000000000000