Stanford:QaGuide

How-to for architects, test and project managers

In this section you find how tos which are related to convert projects from ANT to Maven, to write pom.xml files etc.

How to create a new or convert an existing project

This steps steps have to be done once per project)

Establish or change to Maven directory structure

The following is copied from http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html. It documents the directory layout expected by Maven and the directory layout created by Maven. Please try to conform to this structure as much as possible; however, if you can't these settings can be overridden via the project descriptor.

Path	Description
src/main/java	Application/Library sources
src/main/resources	Application/Library resources
src/main/filters	Resource filter files
src/main/assembly	Assembly descriptors
src/main/config	Configuration files
src/main/webapp	Web application sources
src/test/java	Test sources
src/test/resources	Test resources
src/test/filters	Test resource fiter files
src/site	Site
LICENSE.txt	Project's license
NOTICE.txt	Notices and attributions required by libraries that the project depends on
README.txt	Project's readme

In the table the most relevant paths are marked bold.

Additionally there are at the top level

• pom.xml
• other optional files as properties, maven.xml or build.xml (if using Ant).

In order to get to the new file structure:

• Add folder inside /src: /src/main/java and /src/test/java
• Move /src/edu respectively /test/edu folders into new folders.
• Delete folder test-lib
• Rename “war” to “webapp” and move folder under /src. (here I ran into problems. Really the best way?)
• Add folder /src/main/resources/config. Add to this folder configuration.properties file.
• Add under src/test/java following folders: /client/ and /selenium??
• Delete files in root folder with exception of src. Delete e.g. /etc/,

To move files/directories you can use Tortoise as described in http://stackoverflow.com/questions/62570/how-do-i-move-a-file-or-folder-from-one-folder-to-another-in-tortoisesvn.

Hint: In the developer guide there is a description how to import a project from SVN and immediatelly update the src-folder to the expected structure.

How to upload required artifacts (typicall jar-files) to Nexus repository

There are multiple ways of adding resources to the repository

1. Direct copy (not recommended)
   • Copy resources directly to Nexus subfolder e.g. to /var/nexus/sonatype-work/nexus/storage/thirdparty/edu/stanford/bmir/core/icd.
   • You need to put the file the right directory and give it the name indicating the version number, e.g. /edu/Stanford/bmir/core/protégé-1.0.jar
   • Goto nexus and right click on third party repository: reindex respectively rebuild metadata
2. Uploaded file automatically in due course of a build process (this is recommended for "own" code as Snapshots and Releases).
   • There is nothing to do besides adding the <distributionManagement> tag to the pom.xml and use the deploy plugin. The PC specific settings.xml has to point to the repository as described in the adminstrators guide in section TODO
3. Uploaded file using the Nexus interface (recommended especially for third party artifacts). This option is described in the following subchapter.

upload an artifact to Nexus (part 1): Select repository

upload an artifact to Nexus (part 2): Define GAV parameters

upload an artifact to Nexus (part 3): Reindexing

copy the dependency snippet for pom.xml

For each artifact (jar) you can later copy the dependency information for Maven (into the pom.xml). The code snipped look like:

 <dependency>
   <groupId>edu.stanford.bmir.core</groupId>
   <artifact>protege</artifact>
   <version>1.0</version>
 </dependency>

TODO: define naming convention for groupId. Currently discussed are the following

• protege3
• protege4
• webprotege
• owl

Further reading

• http://www.sonatype.com/books/nexus-book/reference/maven-sect-single-group.html
• http://www.sonatype.com/books/nexus-book/reference/maven-sect-single-group.html
• http://stackoverflow.com/questions/1584763/how-do-i-deploy-to-nexus-hosted-by-secureci

How to write the Maven script (pom.xml)

In our case the pom.xml typically will have the following structure:

• Some general information e.g.

 <modelVersion>4.0.0</modelVersion>
 <groupId>edu.stanford.smi.protegex</groupId>
 <artifactId>dlquery</artifactId>
 <packaging>jar</packaging>
 <name>protege-plugin-dlquery</name>
 <version>0.0.3-SNAPSHOT</version>

• Properties as the Java version
• the <distributionManagement> tag which is necessary if artifacts have to deployed to a repository
• the <dependency/> tags (an example was given above)
• the build part with its plugins (e.g. to compile, test, deploy)
• the reporting part with its plugins (e.g. PMD, Findbugs, JDepend)

It is recommended to use an existing pom.xml as template.

Further hints and readings:

• the version number can be automatically adjusted with a version plugin. The postfix "SNAPSHOT" determines that the artifact won't be uploaded to the release but to the snapshot repository.
• Both repositories (snapshot and release) are defined in the <distributionManagement> section respectively in the /maven/conf/settings.xml file.
• If you are deploying to tomcat, e.g. to perform integration tests, make sure that user and password match with tomcat manger credentials.
• TODO

How to add project to Hudson

Projects can be added from the Hudson administration interface

• Go to Hudson page (e.g. http://bmir-hudson1.stanford.edu).
• Add new job. Select name (e.g. WebProtégé”) and type of project (“Build a maven2 project”).
• Select in section “Source Code Management” the option “Subversion” and add SVN server URL (e.g. http://smi-protege.stanford.edu/repos/protege/web-protege/branches/who-maven/). Keep “Use update” checked. No local module directory. (no password needed?)
• Determine build interval respectively trigger. Currently we use “Build whenever a SNAPSHOT dependency is built”.
• Optionally enable email notification.
• Activate Sonar in “Post-Build-Activities” (Sonar needs to be installed first)

FAQs

Related to reporting

My code coverage statistics aren’t updated. What can I do?

Please change version in pom.xml to next snapshot respectively release number. Don’t forget the configuration.properties file.

I do not get code coverage statistics for my integration tests. What can I do?

Currently nothing, this is the way maven handles the build process.

Related to pom.xml

How can I automatically increase snapshot number?

Make sure that the pom.xml includes the version plugin. this plugin will change the version number within the pom.xml file itself. Therefore the pom.xml is executed twice. This can be automized using Hudson.