OSCAR on Eclipse 12.x

Developers will want to install Oscar on their favourite IDE. These are instructions for Eclipse.

Preface

These basic instructions are adequate for developing Oscar on Eclipse on Ubuntu using a deb install.  You can install Eclipse on any modern OS, but we encourage the better Open Source ones.   Eclipse is java based so if you want a newer version just untar it in your home folder. For other IDE's see Aart De Vries how to for installation on Netbeans (2009) 667Kb pdf.  Although his how to doesn't cover Git,  there now is an experimental plugin for Git on Netbeans called NBGit http://nbgit.org/ 

These instructions do not cover the where why and how of the Git content system, the wonders of Gerrit, nor how to actually use Eclipse: topics which are better covered elsewhere, and/or discovered on your own.

Document Version History

• v1.0 – initial public release to oscarmanual.org– Feb 12, 2011
• v1.1 – Maven step added – July 29, 2011
• v1.2 – Added committing details – Sept 6, 2011
• v1.3 – Added warning about serial commits – May 12, 2013
• v1.4 – Reviewed installation against Eclipse version 4.3 Kepler – Dec 10, 2014
• v1.5 – Updated to reflect Github login – Sept 22, 2015

The document is based on instructions from Ted Leung and is copyright © 2011-14 by Peter Hutten-Czapski under the Creative Commons Attribution-Share Alike 3.0 Unported License

Register for Gerrit

We encourage every developer to sign up, even if you don't commit code right now, gerrit will give you the ability to view and comment on other committed patches etc.  You can register using your Github login.  Just navigate to (https://source.oscartools.org:8080/)

On the Gerrit main screen you should see a register option on the top right of the screen.

On the main registration screen :
    - For "Full Name" enter the persons name and click "save changed" (yes you actually need to click that now).
    - For "select a unique username" this will become your ssh access username, We'll use your email address (before the @ sign) as a standard. You need to click "select username" now.
    - For "Register an SSH public key" : if you already know or have SSH keys you can just provide it, otherwise do the following : 

~$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/peter/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/peter/.ssh/id_rsa.
Your public key has been saved in /home/peter/.ssh/id_rsa.pub.

Do not enter a passphrase when it asks. This means it will be easier for you to sign in AND... if you machine is compromised, your gerrit user is compromised and the corresponding server key should be deleted, you'll need to tell the gerrit administrator and or login to the gerrit web site and delete this key.

 Now cut and paste the contents of "~/.ssh/id_rsa.pub" into the text area on the web page.

Click add and it should list it as an added key on the screen.
    - now on the bottom of the screen there's a link that says "continue" click that, now you should be at the your "code review dashboard" screen.

At this point, if your Eclipse was already running, you need to stop it and start it again. Eclipse caches ssh key information.

Installing Eclipse and Maven

First we need to install  Maven

sudo apt-get install maven2

Or, as you are in a GUI desktop environment anyway, use Synaptic to do the same thing

Now you need to install the EGit plugin

Installing EGit Plugin

Navigate to Eclipse  >  Help > Install New Software and add in

http://download.eclipse.org/egit/updates

Press Add and OK

Now review what you are to install, Here we demonstrate we are installing version 0.10.1 of EGit

 If you are installing Eclipse for the first time you will be asked to review and accept the licenses.

 and you will need to accept the veracity of the certificate

Configuring the Plugin

You will need a file in your home directory calls .gitconfig, which has a standard ini or property file structure.  Eclipse will generate it for you. 

• Click Window > Preferences > Team > Git > Configuration
• Click New Entry... and enter the key value pair user.email and your email that you registered on the gerrit site with 
• Click New Entry... and enter the key value pair user.name and your name
• Other options such as core.editor can also be added
• when you are done it should look like this:

Cloning Oscar into Eclipse

Click File > Import... > Projects from Git > clone.

Add the Clone... (Kepler clone URI)

The repository details should be provided for your git/gerrit installation, 

You will want to use "ssh://xxxx@source.oscartools.org:29418/oscar". 

Just replace xxx with your Gerrit repository user name
Note that you do not need to enter a password. 

You can uncheck "Store in Secure Store" and you won't have to sign in every time you open Eclipse.

(BTW: The test repository shown below is just that.  Its a sandbox that you can use to get used to the "fetch" and "push" of it without worrying about anyone noticing.)

 You can select any branch,  but scroll down to find "master".

You will be asked for the local destination.  You should accept the default unless you already have a directory of that name

Then you will be asked for a secure password if you left the checkbox "store in a secure store" earlier

and then you will be cloning Oscar from master into your local repository

Almost there

[Next >] will determine how to share the imported project.  Lets use the defaults.

Identify the imported project by clicking on the checkbox

Click the [Finish]  button and add Maven to your classpath

Window > Preferences > Java > Build Path > Classpath Variables > [New...]

Prior to adding the M2_REPO to Eclipse, you need to open a terminal and run mvn install command to create  /home/yourHomeDirectoryName/.m2

Add the M2_REPO and point it to your  /home/yourHomeDirectoryName/.m2/repository folder

and here you have it, Oscar in Eclipse

For other Oscar projects  create a new workspace and repeat the above steps starting at "ssh://xxxx@source.oscartools.org:29418/{project}"

where {project} is taken from the available repositories such as

• hhr
• integrator
• myoscar_client
• myoscar_client2
• myoscar_server
• myoscar_server2
• oscar_patient_portal
• oscar
• oscar_apps
• oscar_documents
• signature_pad
• test
• utils

Making Changes

Now say you've created new files in the project and altered some existing ones.

As a note, you should try to do a "team -> pull" before doing a commit, this will help ensure there are no commit conflicts, if there are your commit will not be mergable by gerrit and you'll have to go through a rebase of your commit before it can be merged. If you right click on the project, go to team > pull.

If you right click on the project, go to team > commit. You'll see the commit screen. Notice on eclipse it will list the tracked and untracked file and by default they will be "git added" and "git commited" at the same time. Now when you commit, it's commited locally. This means no one else except you has these changes still.

Add the information needed to identify the commit.

IMPORTANT: Commits should be labelled with the ID of the bug or Feature Request from Sourceforge that reflects the OSCAR Change request or Oscar bug that is being addressed.

Now to share these changes with everyone else, i.e. committed to the main repository... (You must have committed locally first) 

Right click on the project, go to team -> push to upstream

A boring screen will show the uploading of file(s).

If this is the first time you've pushed, you'll need to fill in a push specification according to if its going to the trunk or an established branch as below.

• source ref="HEAD", destination ref="refs/for/master", 
• source ref="HEAD", destination ref="refs/for/RELEASE_12_1",

select add spec, check the box on the bottom saying save spec... so you don't have to do this again. Just click "finish" (next doesn't show anything interesting).

Assuming you are pushing as above to the trunk (the "master" branch) after you have pushed the commit

If you go back to the gerrit web page you should see the change is pending review now as listed in Open.

Note that at this point, you and the central repository are NOT in sync, the files at the central repository must be approved first.

1. First the system will check the style of your code and attempt to build.  
2. When that passes a check-mark will appear under the 'V'.  Without this the commit will be blocked from passing
3. Then humans will review the code.  Regular users are usually able to +1 review.  Only those responsible for the repository can +2. 
4. Once +2 approved a check-mark will appear under the 'R' and the code will be merged into the central repository

Even after the changes on the central repository are approved, you will get notifications by email, you must pull (or sequentially fetch and merge) again before you and the central repository are in sync (yes even if the files happen to be the same on the 2 servers, the pointers are not in sync until you merge).  

IMPORTANT: READ THIS UNLESS GERRIT IS OLD HAT TO YOU

When to commit locally and when to push remotely

Generally speaking you should commit locally for independent small units of work. So as an example if you are working on a feature, you may have incremental phases in completion of that feature. You should commit at each phase, the code should at least compile and run.

Generally speaking pushing remotely can be done for any commit. There is generally no need to bundle up multiple commits into one big push. The difference between a push and commit maybe more important if you're working offline as you can only push while online.

The reason for the above is because of the review model of gerrit. You don't want to do one big commit because it will be a nightmare to review and approve. Think about the example of converting 300 DBHandler calls into maybe 100 JPA objects. If that was 1 commit, it would take for ever to review and verify that commit. If you made 300 separate commits, the review process could at least proceed incrementally and in manageable size chunks. The push is for a similar reason, if you had 300 separate commits and you pushed all at once at the end of 6 months, there will be a sudden flood of 300 commits to review and it would be a huge backlog. If you pushed those 300 commits over a 6 month period, review of the commits could have started as soon as the first push was done.