Difference between revisions of "Papyrus/Papyrus Developer Guide/How to Contribute to Papyrus with Gerrit"

Revision as of 10:11, 3 February 2015

Using Gerrit, you can contribute to the Papryrus project, even if you aren't a committer.

Sign in the eclipse development chart

• Create an Eclipse Bugzilla account : https://dev.eclipse.org/site_login/createaccount.php

This step is your average account creation, and it will require you to visit a mail sent URL to validate the account.

• Sign the CLA : https://wiki.eclipse.org/CLA

This can be done ( by visitiing the following link: https://projects.eclipse.org/user/login/sso ) once logged in by clicking on Contributor License Agreement and following all the instruction on this same page.

• Activate your Gerrit account : https://git.eclipse.org/r/

The id and password , just as your sign-in information on the eclipse website, are the mail address you used to create the eclipse account and the associated password, no need to create a new one.

Retrieve Papyrus code

To retrieve the papyrus code:

• via git : git://git.eclipse.org/gitroot/papyrus/org.eclipse.papyrus.git
• via ssh : ssh://[committer_id]@git.eclipse.org:29418/papyrus/org.eclipse.papyrus.git, where [commiter_id] is your Gerrit id.
• via http : http://git.eclipse.org/gitroot/papyrus/org.eclipse.papyrus.git

Read more information in https://wiki.eclipse.org/Papyrus_Developer_Guide#Cloning_the_Git_repository_and_importing_the_code

Configure access

Via EGit, To allow the user to commit anything Git will have to know your id and email. as such you can enter those variables in Preferences>Team>Git>Configuration and add the two entries:

• key:user.name / value:[your name]
• key:user.email / value:[your email]

Furthermore your will have to add the ssh key (if you want to commit via ssh) to Preferences>General>Network Connection>SSH2 by setting the path to your .ssh folder and adding the name of your key to the private keys list. If you do not have an ssh key yet, you can generate one using PuTTYgen ( http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html ). Select Key>SSH-2 RSA key in 2048 bits in length and just click generate. It is important to know that the key is generated by the random mouvements of the mouse inside the window, so don't wait for it to generate itself. then, save both keys in your .ssh folder.

Via command lines, For the configuration:

• git config --global user.name "[your name]"
• git config --global user.email "[your email]"

For the ssh key, just type the following command:

• ssh -keygen -t [your key's name] -b [number of bits in length]

As an example here is what this should look like when viewed inside your eclipse's Preferences page:

Configure push for Gerrit

Because you're not an official Papyrus commiter, you can't just commit your code on the papyrus git repository; you have to submit your contribution via the commit refs/for/master branch. You can configure EGit for push on that particular branch:

• On the Git Repositories view, open Remotes
• Add a new Remote by right clicking on Remotes, then choose Create Remote..., and choose a new name (for example Gerrit)

N.B. : you can also choose to modify the origin remote.

• Configure Gerrit for this remote by right clicking on it, and Gerrit Configuration

You now have to configure the repository URI :

• Choose your preferred protocole (http, https, ssh)
• Enter the papyrus URI :
  • via ssh : ssh://[committer_id]@git.eclipse.org:29418/papyrus/org.eclipse.papyrus.git, where [commiter_id] is your Gerrit id.
  • via https : https://[committer_id]@git.eclipse.org/r/p/papyrus/org.eclipse.papyrus

• The above push configurations already contain your Gerrit id in the adress, and therefore the Gerrit id field will be updated automatically in the configuration window.
• You may want to enter you password so that you won't have to type it on each push.

If you're experiencing problems, please verify that you're pushing on refs/for/master (Or refs/drafts/master for hidden review)

How to commit using EGit

When you're not an official Papyrus commuter, you have to sign-off and change-id all your commits You can do that easily using EGit by just clicking the two following buttons:

The first line of your commit comment should be the bugzilla task number and it name; example : Bug 12345 - The name of the bug you fixed. The first commit on a Bug won't have a change-id as this will be created when the commit is pushed and accepted by Gerrit. The change-id can be retrieved by visiting the pushed commit on Gerrit.

The change-id generated should appear in the footer of your next commit message. The change-id will change with every recorded push on Gerrit so be careful to update it accordingly the next time. With EGit the "amend previous commit" button should fill the new commit's message with the updated fields.

How to commit using commands

The editor used in this section is Cygwin ( https://www.cygwin.com/ ), to which we added the specific git packages: git-completion, gui, svn and fast version control system. To install them choose a site, such as mirrors.kernel.org To make the display easier to read, it is usefull to run the following command: git config --global color.ui true

First push

Having created an empty file (using the touch command) inside the git repository, git sees it as a modification and therefore the git status command shows the file as untracked. We add it to the index of the next commit using git add [file name] and as you can see by the second git status the file testGerrit.txt is in the "Changes to be committed". The next step is to create the commit itself. For this purpose we run the git commit -m "[your commit message]" --signoff command. This command decompose itself in 3:

• The actual order of commit, by using the commit keyword
• The message we want to asociate with the commit, by using -m an entering the commit message between comas
• The addition of the signature without which your commit will be refused, by adding --signoff (or just -s). This signature is comprised of your previously defined user name and user email.

Before pushing on gerrit it is preferable to update your local branch from the remote as that should prevent merge conflicts if your change is accepted and merged.

• To do this we used the git fetch ( short for: git fetch [name of the git remote], and in this example the remote of the repository is named "origin" ) that will import all the changes (commits) that happened since the last update of the branch or, if no update were done, since the creation of the branch.
• And git rebase ( short for: git rebase [name of the remote branch], which in this case is "origin/master" ) that will detach all the work done on the local branch, patch the local branch with the changes that happened on the remote branch and replay the work on top of them, effectively giving you an updated branch and clean base to push your new commit.

Then, we push the commit onto Gerrit. It will signal you if the build incorporating your changes has failed and allow your code to be reviewed before being merged.

You will be able to see your contribution by opening Gerrit's web interface ( https://git.eclipse.org/r ). Filters can be applied in the search fieldbox. Useful ones in this case are:

• status:open, that will only show the opened and not yet reviewed commits
• project:papyrus/org.eclipse.papyrus, that will only show commit related to the papyrus project

And this is what your commit details will look like:

More information of how to use git on Contributing via Git