Mailing Lists

The first step in getting involved with the Virtual Library project is to subscribe to the user and/or development mailing lists. Questions or comments about how to use the application should be directed to the user list. All discussion related to the code or design of the VL takes place on the development list.

SourceForge Trackers

Bug reports should be filed using the Virtual Library Bug Tracker.

New feature requests should be discussed first on the development list and then recorded in the Virtual Library Feature Request Tracker.

Subversion Repository

The Virtual Library team uses Subversion, hosted at SourceForge, as our source control system. Documentation and download instructions for Subversion client software is available on the Subversion web site. The Online Subversion Book is a great resource for those new to Subversion and a good reference for experienced users.

To checkout a local copy of the main development sources, use:

svn checkout https://vlibrary.svn.sourceforge.net/svnroot/vlibrary vlibrary

You can also browse the VL sources online using the

online svn viewer.

Building the Virtual Library

The Virtual Library uses Apache Maven for build, test and web site generation. To build the Virtual Library, you need to have Maven (version 2.0.x) installed locally, as well as a Java Development Kit (version 1.5 recommended). You can download maven from the Maven download site. The great thing about Maven is that this is the only distribution that you have to download and install manually - Maven will automatically download all of the other components that the Virtual Library (or any other Maven-built application) depends on.

Once you have installed Maven and checked out a local copy of the vlibrary sources, to build the application and run the tests, from the top-level directory of the checkout (the directory that contains the file pom.xml), execute the command:

mvn clean test

The first time you execute a build, especially if your maven installation is new, Maven will take a long time downloading all of its own dependencies as well as those of the VL. Do not despair, things will go much faster in subsequent builds, as the required components are cached locally.

The build should succeed, with all tests passing. You should make sure that sources build clean and tests pass after any change that you make to the VL code.

To create a war file, including all dependent jars, execute:

mvn clean war:war

To generate the project web site:

mvn clean site

Submitting patches

Patches to address bugs, implement new features, or improve the VL documentation are always welcome. Patches that adhere to the guidelines below will be easiest for the VL team to work with, so will be most likely to be committed.

Patches should be in unified diff format. You can generate acceptable patches using the svn diff command, like so (assuming your command shell understands >>, which means pipe the output to the file):

svn diff some-file-path >> patch_name.patch

where some-file-path is a relative path to the sources that you have changed and patch_name.patch is the name of the patch file being created.

For example, if your patch includes a change to the source file src/main/java/org/sourceforge/vlibrary/user/dao/AutorDAO.java and you have (of course :-) also included a new test case in src/test/java/org/sourceforge/vlibrary/user/dao/AuthorDAOSpringJDBCImplTest.java, you should first have a look at the changes by executing svn diff from the /src directory in your local checkout. The output will show all changes in the source tree below that point. If you have changed no other files than those above, you will see just the changes that you want to see implemented in your patch. Once you are satisfied with the patch, pipe the output of the svn diff to a file and attach the file to a tracker issue (creating a new one if necessary).

Avoid introducing extraneous formatting changes with your patches, as these make the diffs harder to read and clutter up the commit messages when the patches get committed.

Code changes should always include unit tests. An ideal patch supplied for a bug includes a unit test that fails with the current code, illustrating the bug, and succeeds when the patch is applied. Similarly, patches for new features should include tests that verify that the new feature is correctly implemented.

Code changes should always include full javadoc and not generate any new javadoc warnings, pmd or checkstyle errors.

Thanks in advance for your contributions to the Virtual Library project!