Developer Manual

Introduction

This wiki page is intended to present the project, thinking on a developer that continues the work done so far. Thus, this manual is a reference for new developers who join the project with the consequent lack of knowledge of the system.

First of all, if you do not know anything about maven, please, read a bit.

What Maven is -> http://maven.apache.org/what-is-maven.html Maven in 5 minutes -> http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html

To understand what Maven is and how works is quite important because all project is build using Maven. For example, we use maven to perform tests, to get dependencies, to generated a site with info about the project (metrics, test results, etc.) and to deploy new versions of the project in Maven Central repositories.

Once you have understood this, install the following software in you computer:

Install Java JDK6

To develop this project, we have used JDK6 because JDK7 had some problems when we tried to perform release with maven. Maybe this problem has been solved in recent versions, but we have not checked. Anyway, ensure that you JAVA_HOME system variable is properly configured. The method to define this variable depends of the operating systems. If you do not know how to do it, search in Google. ;)

Install Maven

1. Download the last version of Maven in zip format from the official Maven page. http://maven.apache.org/
2. Unzip it in the location where you want to have it installed.
3. Modify the path by adding the location of the bin directory located inside the unzipped folder. For example: C:\Program Files\apache-maven-3.0.3\bin
4. Test Maven runs correctly by writing ’mvn’ in the console.

Note: We have used maven 3.0.3 but any newer version should work without problems.

Install Eclipse and proper plugins

Download and install Eclipse Classic. We are using 4.2.2. "Juno".

Github

A Github repository is used as control version and as issue management systems. The eclipse plugins used to integrate git commands with the eclipse IDE is egit (http://eclipse.github.com/).

Furthermore, Github Mylyn connector (see the link above) is used to get all project issues in eclipse IDE or comment any progress in a specific task.

Useful advice: you can close an issue in a commit message. See this https://help.github.com/articles/closing-issues-via-commit-messages

GPG

To sign your packages when you perform a release and you want to deploy your project in the maven central repositories, you must install GnuPG or GPG http://www.gnupg.org/

You can follow the next tutorial to understand the maven release process: https://docs.sonatype.org/display/Repository/How+To+Generate+PGP+Signatures+With+Maven

Git in console

To execute such as mvn deploy or mvn release:prepare, you need to install git in console mode.

First of all, be sure that your git client is configured with the correct "user.email" and "user.name" variables and the system has access to these variables. In other words, check the git configuration using "git config --system --list" command.

Note: I had some problems with these. In the end, I configured my user.email and my user.name in my git project configuration (git config user.name), git global configuration (git config --global user.name) and git system configuration (git config --system user.name).

Maven

We have used the Maven plugin for eclipse m2eclipse (http://www.eclipse.org/m2e/), which let as saving some time and efforts. It allows us the automation of running test, building the javadoc and the .jar file, and the most important, include other dependencies to the building process, obtaining great information of our project without any effort. One example of these dependencies is Cobertura, which checks the testing level of our system and indicates the lines of code that have never been tested. It warns as well about the number of TODO’s and FIXME’s in the code. For this functionality tests must be written in src/test/java.

To configure all maven issues can be a headache. So for this reason, a few advices are offered here.

When you execute "mvn release:perform", maven launches a lot of console instances by itself. To ensure that these instances has rights to access the required directories, be sure that you execute that command with administrador rights (or sudo, as you like). If no rights are given, gpg plugin will not be able to sign the packages to release a new version in the maven central repositories. Furthermore, you need to configure your gpg profile in your settings.xml.

<profiles>
	<profile>
		<id>release-sign-artifacts</id>
		<activation>
			<property>
				<name>performRelease</name>
				<value>true</value>
			</property>
		</activation>
		<properties>
			<gpg.secretKeyring>your path</gpg.secretKeyring>
			<gpg.publicKeyring>your path</gpg.publicKeyring>
			<gpg.passphrase>your passphrase</gpg.passphrase>
		</properties>
		<build>
			<plugins>
				<plugin>
					<groupId>org.apache.maven.plugins</groupId>
					<artifactId>maven-gpg-plugin</artifactId>
					<version>1.4</version>
					<executions>
						<execution>
							<id>sign-artifacts</id>
							<phase>verify</phase>
							<goals>
								<goal>sign</goal>
							</goals>
						</execution>
					</executions>
				</plugin>
			</plugins>
		</build>
	</profile>
</profiles>

Finally, check that your local settings.xml file contains all required information of all servers (usernames, passwords and configurations).

For example, to deploy a new version of the site generated by maven (mvn site site:deploy), you must configure the github credentials and specify the branch (gh-pages).

<servers>
	<server>
		<id>site-github-web</id>
		<username>your username</username>
		<password>your password</password>
		<configuration>
			<scmVersionType>branch</scmVersionType>
			<scmVersion>gh-pages</scmVersion>
		</configuration>
	</server>
</servers>

But take care about to use different configurations for scm developer connections. In this case, it should be:

<servers>	
	<server>
		<id>github.com</id>
		<username>your username</username>
		<password>your password</password>
	</server>
</servers>

And to deploy releases and snapshots:

<servers>
	<server>
		<id>sonatype-nexus-staging</id>
		<username>your username</username>
		<password>your password</password>
	</server>
	<server>
		<id>sonatype-nexus-snapshots</id>
		<username>your username</username>
		<password>your password</password>
	</server>
</servers>

If you use the same configuration, all files will be stored in the same branch (master brach if you use the second option or gh-pages if you use the first one).

To use these notes, please check the pom.xml file in the project root folder.

Download the project

1. Download Shanks-core project from github using "Git repositories" view in eclipse. You can automatically import any project in the repository to the workspace checking the option in the wizard windows that appears. https://github.com/gsi-upm/Shanks
2. Execute Maven Install over the whole project of Shanks-core. Right-click in the project -> Run as -> Maven install. To execute mvn install or mvn tests you can use the m2eclipse plugin (i.e. execute these commands from the eclipse GUI). But to execute complex maven commands, I recommend you to launch them from console because many problems occurs with access right since eclipse is an application. For example, gpg need administration access to sign packages.

Final test

To ensure that you have all configured in your computer, please execute some maven commads as ADMINISTRATOR/ROOTin the following order:

mvn install
mvn compile
mvn test
mvn site
mvn site:deploy
mvn clean
mvn release:clean
mvn release:prepare
mvn release:perform

Notice:

• mvn site:deploy will deploy a new site in gh-pages branch in github repository
• mvn release:prepare will deploy a new tag in github repository
• mvn release:perform performs a lot of tasks. The most important are that it deploys a new version of the software in the maven repositories and it uses gpg to sign the packages. Furthermore, it deploys a new version of the maven site in gh-pages branch of github repository

If no error appears, congratulations!! :) All works.

If you don't want to release a new version of the project when you are performing these tests, you must follow these steps:

1. Go to http://oss.sonatype.org, log in and go to "Staging repositories". Then, drop the new one created by "mvn release:perform" command.
2. Delete the last tag created by "mvn release:prepare" in github repository. Check this link -> http://nathanhoad.net/how-to-delete-a-remote-git-tag
3. Return to the previous version in pom.xml. For example if you were working in version 0.1.1-SNAPSHOT, after you perform the release, the new version will be 0.1.2-SNAPSHOT. Then, you should change that for the correct version and commit&push the correct version of pom.xml file.

Release a new version in Maven Central Repositories

This is an important point of this developer manual. To perform a new release, you only need to execute this command:

mvn release:clean release:prepare release:perform

or execute every command alone to ensure that the command was successfully executed before you launch the next one:

mvn release:clean
mvn release:prepare
mvn release:perform

Once these commands were executed successfully,

1. Go to http://oss.sonatype.org, log in and go to "Staging repositories".
2. Select the repository that contains the release and click "Close" option. Leave a comment about why you are closing this repository (you can leave it in blank). Note: Many other repositories could appears, but don't worry. They are only backups performed by Sonatype.
3. Once the repository is closed, select again the repository and click in "Release" option and leave a comment if you like.
4. That's all! Check that the release is available in the central repository searching it.

Source code organization

The source code has the following structure:

shanks-core/src/main/java
	es.upm.dit.gsi.shanks
		agent
			action
			capability
				creation
				movement
				perception
				reasoning
					bayes
			portrayal
		model
		notification

//TODO explain what these packages contains