Setting up Eclipse

The development environment for SmartWeb is based on standard Eclipse IDE supported by Subclipse, Maven2 and JBoss plugins.

To set up the standard environment start downloading the latest Eclipse SDK release available for your platform then uncompress the package and start the IDE. Now install the plugins using the Eclipse Update Manager and the following informations:

• Subclipse Update Site (http://subclipse.tigris.org/update_1.2.x)
• Maven 2 Integration Update Site (http://m2eclipse.codehaus.org/update/)
• JBossIDE Update Site (http://download.jboss.org/jbosside/updates/stable)

With the environment setted up all you need to start your developer activity are the latest core and modules sources. To reduce the effort needed to introduce newbies we have decided to split each module on a separate project so if you wish to contribute to a single module all you need are those module sources!

To get the previous statement in practice you should create a new project checking it out from SVN using an anonymous connection to our repository and name the project accordingly (eg. smartweb-registry, smartweb-auth or simply smartweb to work on the core).

Once the project is downloaded the Eclipse IDE will automatically start to build the sources for you: if this is your first time on smartweb and/or Maven the process could be a few minutes long (depending on your internet connection speed) as Maven will need to download it's plugins and the project dependencies. During the download phase you can incur into a dependancy resolution error on two libraries:

• javax.j2ee:j2ee:jar:1.4 available in every J2EE server or available within the J2EE SDK downloadable from here
• javax.transaction:jta:jar:1.0.1B downloadable from here

Once you get those libraries on your hard drive you must install them into your Maven Repository with the following commands:

$ mvn install:install-file -DgroupId=javax.j2ee -DartifactId=j2ee -Dversion=1.4 -Dpackaging=jar -Dfile=/path/to/j2ee.jar/file
$ mvn install:install-file -DgroupId=javax.transaction -DartifactId=jta -Dversion=1.0.1B -Dpackaging=jar -Dfile=/path/to/jta.jar/file

One last step is required if you wish to verify unit test code coverage as our choice is Clover which requires a license to be executed: copy the clover.license file from the smartweb root folder (the trunk folder in subversion) into your <home>/.m2 folder. Now everything should works fine and you can start developing with us!

Finding some work to do

First of all you need something to work on! Unless you have found a particular issue in the tracking system you would like to work on, the SmartWeb Team has categorized a few issues that we could use your help to solve them. Other things which needs your help can be found on the ToDos page and FixMe page which are usually updated frequently.

When you find a issue you would like to work on add a comment in the issue log so the core developers and other people looking for work know that someone is already working on it.

Creating and submitting a patch

When you have either completed an issue or just want some feedback on the work you have done, create a patch and attach the patch to the issue in question. We have a couple of guidelines when creating patches:

• Always create the patch from the root of the SmartWeb project or module, i.e. where the pom.xml file is.
• If this was a new piece of work without a related issue, create an issue for it now.
• Name the file <artifact id>-<issue number>.patch.
• Attach the patch to the issue you were working on (do not paste its content in as a comment though). When adding the patch add a comment to the issue explaining what it does. Shortly after, someone will apply the patch and close the issue.

  An example on how to create a patch from the command line:

  $ svn diff > smartweb-123.patch

  If you are picking up an issue with a existing patch attached to the issue you can apply the patch to your working directory. If the patch is in a local file smartweb-auth-123.patch and you want to apply that use this command:

  $ patch -p0 < smartweb-123.patch

  A couple of notes:

• If you are using another tool for creating patches, make sure that the patch doesn't include absolute paths. Including absolute paths in the patch will make the useless for us as we most likely don't have the same directory structure as you.
• Make sure that you follow our code style.

Other useful Subversion commands while developing

If you've done a chunk of work and you would like ditch your changes and start from scratch use this command to revert to the original checkout:

$ svn revert -R .

The -R argument means that the command will recurse down all directories and revert all changes.

Before committing code to the Subversion repository we always set the svn:ignore property on the directory to prevent some files and directories to be checked in.

Patch acceptance criteria

There are a number of criteria that a patch will be judged on:

• Whether it works and does what is intended. This one is probably obvious!
• Whether it fits the spirit of the project. Some patches may be rejected as they take the project in a different direction to that which the current development community has chosen. This is usually discussed on an issue well before a patch is contributed, so if you are unsure, discuss it there or on the mailing lists first. Feel free to continue discussing it (with new justification) if you disagree, or appeal to a wider audience on the mailing lists.
• Whether it contains tests. It is expected that any patches relating to functionality will be accompanied by unit tests and/or integration tests. It is strongly desired (and will be requested) for bug fixes too, but will not be the basis for not applying it. At a bare minimum, the change should not decrease the amount of automated test coverage. As a community, we are focusing on increasing the current coverage, as there are several areas that do not receive automated testing.
• Whether it contains documentation. All new functionality needs to be documented for users, even if it is very rough for someone to expand on later. While rough is acceptable, incomplete is not. As with automated testing, as a community we are striving to increase the current coverage of documentation.

  Above all, don't be discouraged. These are the same requirements the current commiters should hold each other to as well. And remember, your contributions are always welcome! Related Projects

Commit Message Template

Commits should have a message that follows this template:

[issue1, issue2] <<comment>>
Submitted by: (when it was a patch, put that persons name there)

issue can be omitted if there was no relevant issue, though it is strongly encouraged to create one for significant changes.

Submitted by only needs to be specified when a patch is being applied for a non-committer.

For example:

[smartweb-registry-1456] Added the foo to the bar
Submitted by: Baz Bazman

Generating site

Site generation requires some additional steps to be performed correctly. First of all you need Subversion command line tool installed onto your computer and available through command line which usually mean to have the svn binary executable into your environment PATH. As a second step you need to issue a request to the SourceForge subversion repository to accept permanently the SourceForge certificate: this step could be simply performed running

svn log https://smartweb.svn.sourceforge.net/svnroot/smartweb/trunk

Answer permanently upon certificate acceptance request.

Performing Releases

Only project leaders or managers are allowed to release a new version to the public. The release process can be splitted into the following pratical steps:

• execute a mvn clean test command to verify the project consistency and there are no test errors or failures;
• execute a mvn release:prepare -DdryRun=true command to verify your tree consistency against the repository;
• execute a mvn release:clean release:prepare command to update the repository with the new release pom;
• execute a mvn release:perform command to generate all packages and the documenting site;
• execute a mvn site-deploy to upload the generated site to Sourceforge;
• execute a mvn deploy to upload the generated artifacts to iBiblio.