View source for 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.
{| border="1"
!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: <tt>/src/main/java and /src/test/java</tt>
* Move <tt>/src/edu</tt> respectively <tt>/test/edu</tt> 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 <tt>/src/main/resources/config</tt>. Add to this folder <tt>configuration.properties</tt> file.
* Add under <tt>src/test/java</tt> following folders: <tt>/client/</tt> and <tt>/selenium</tt>??
* 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
# Direct copy (not recommended)
#* Copy resources directly to Nexus subfolder e.g. to <tt>/var/nexus/sonatype-work/nexus/storage/thirdparty/edu/stanford/bmir/core/icd</tt>.
#* You need to put the file the right directory and give it the name indicating the version number, e.g. <tt>/edu/Stanford/bmir/core/protégé-1.0.jar</tt>
#* Goto nexus and right click on third party repository: reindex respectively rebuild metadata
# 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 <tt>settings.xml</tt> has to point to the repository as described in the adminstrators guide in section TODO
# Uploaded file using the Nexus interface (recommended especially for third party artifacts). This option is described in the following subchapter.

{|
| [[Image:nexus-upload-1.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 1)|upload an artifact to Nexus (part 1): Select repository]]
| [[Image:nexus-upload-2.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 2)|upload an artifact to Nexus (part 2): Define GAV parameters]]
| [[Image:nexus-upload-3.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 3)|upload an artifact to Nexus (part 3): Reindexing]]
| [[Image:nexus-get-dependency.png|thumb|upright|alt=Screenshot how copy the dependency snippet for pom.xml|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 <tt><distributionManagement></tt> tag which is necessary if artifacts have to deployed to a repository
* the <tt><dependency/></tt> 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 <tt>pom.xml</tt> as template. 


Further hints and readings:
* the version number can be automatically adjusted with a version plugin. The postfix "<tt>SNAPSHOT</tt>" 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 <tt><distributionManagement></tt> section respectively in the <tt>/maven/conf/settings.xml</tt> 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==
[[File:hudson-configure-svn.png|thumb|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.