Create a Project Report using Maven

If your project has the csco-parent-java (at least in version 1.0.10-SNAPSHOT) as one of its parents, you are able to generate a report for your project providing usefull information about your project and some analytical checks to ensure your project doesn't contain any errors.

To ensure the correctness ond completeness of the report, please make sure your pom.xml file contains all needed parts, see the template pom.xml (Keep in mind, that in the template are some variables that have to be replaced by your project variables).

The reports

• Project Information:
  • About: shows the description of the projects (as described in the pom.xml)
  • Project Summary: lists other related information of the project
  • Project Team: provides information on the members of the project.
  • Continuous Integration: This is a link to the definitions of all continuous integration processes that builds and tests code on a frequent, regular basis.
  • Issue Tracking: This is a link to the issue management system for this project. Issues (bugs, features, change requests) can be created and queried using this link.
  • Dependencies: This document lists the project's dependencies and provides information on each dependency.
  • Dependency Information: This document describes how to to include this project as a dependency using various dependency management tools.
  • Dependency Management: This document lists the dependencies that are defined through dependencyManagement.
  • Project Plugins: This document lists the build plugins and the report plugins used by this project.
  • Distribution Management: This document provides informations on the distribution management of this project.
  • Source Repository: This is a link to the online source repository that can be viewed via a web browser.
• Project Reports
  • Dependency Updates Report: Provides details of the dependencies which have updated versions available.
  • Plugin Updates Report: Provides details of the plugins used by this project which have newer versions available.
  • Property Updates Report: Provides details of properties which control versions of dependencies and/or plugins, and indicates any newer versions which are available.
  • Changes: Changes report on releases of this project.
  • Change Log: Generated change log report from SCM.
  • File Activity: Generated file activity report from SCM.
  • Developer Activity: Generated developer activity report from SCM
  • JavaDocs: JavaDoc API documentation.
  • Test JavaDocs: Test JavaDoc API documentation.
  • Source Xref: HTML based, cross-reference version of Java source code.
  • Test Source Xref: HTML based, cross-reference version of Java test source code.
  • Tag List: Report on various tags found in the code.
  • Surefire Report: Report on the test results of the project.
  • Cobertura Test Coverage: Cobertura Test Coverage Report.
  • FindBugs: Generates a source code report with the FindBugs Library.
  • CPD: Duplicate code detection. (only available if there is duplicated code)
  • PMD: Verification of coding rules.
  • Checkstyle: Report on coding style conventions.
  • JDepend: JDepend traverses Java class file directories and generates design quality metrics for each Java package. JDepend allows you to automatically measure the quality of a design in terms of its extensibility, reusability, and maintainability to manage package dependencies effectively.

In general the Tag List, Findbugs, CPD, PMD and Checkstyle reports should not contain any entries. If your report contains any entries, that you can't resolve or would bloat your code unnecessary, please keep in mind, that not all rules of the static code analysis tools are usefull for us. In such a case please contact Andreas Schaller or any other member of the CSCOAP group or the Java Developer Community at GSI.

The Surefire and Cobertura Test Coverage reports shows how efficient your code is tested. Please keep in mind, that it is not feasible and not recommended to reach a line coverage of 100%. A good value of testing can be a line coverage of about at least 70%. The branch coverage should be as high as possible.

The Tag List is also included in eclipse by default, Findbugs, PMD, Checkstyle and code coverage tools can also be included in eclipse by installing the different plugins. If you install these plugins you have to configure them so that they won't print out different results as the maven report. The maven report is always the one that is comparable between different eclipse installations.

The report generation

Precondition: All dependencies have to be deployed to the artifactory (or at least local), otherwise maven will download older versions of the dependencies to build your application which might fail.

To generate the report you have three posibilities:

• generate the report locally
  • run command mvn site
  • this is the prefered option
  • generates Project Information and Project Reports in your projects target folder
• generate the report and deploy it
  • run command mvn site-deploy
  • deploys Project Information and Project Reports to the configured snapshot location (<docu.url.snapshot>)
• generate the report and release it
  • is done when you release your project using the release process
  • can be done manually with command mvn site-deploy -P release,java-packaging-tools
  • releases the Project Information to the configured release location (<docu.url.release>)
  • this option generates only the Project Information, no source codes or code analyses are reported! In eclipse: right click on projekt -> Run As -> Maven build... -> choose the goeal from above

To keep the amount of errors (especially checksstyle errors) it is recommended to configure eclipse as described here.

Custom Changelog Site

Scince parent version 2.0.3 it is possible to generate a custom changelog site for your product. Just add the file changes.xml to your project roots directory. The content of the changes.xml file may look like this ( see full spec):

<document xmlns="http://maven.apache.org/changes/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/changes/1.0.0 http://maven.apache.org/xsd/changes-1.0.0.xsd">
    <properties>
        <title>My Applications Changelog</title>
        <author email="a.schaller@gsi.de">Andreas Schaller</author>
    </properties>
    <body>
        <release version="0.0.5" date="2016-03-23" description="second version">
            <action dev="schaller" date="2016-03-21" type="fix">
                Fix cool feature.
            </action>
            <action dev="schaller" date="2016-03-19" type="add">
                Add cool feature.
            </action>
        </release>
        <release version="0.0.1" date="2016-03-01" description="first version">
            <action dev="schaller" date="2016-03-01" type="add">
                Introduce the application to solve a given problem.
            </action>
        </release>
    </body>
</document>

Note that the "dev" attribute of the "action" node refers to an id of a person specified in the pom "developers" node. If a person is not mentioned there you can also write the full name or any abbreviation.

Custom Report Sites

You can also add custom project specific sites to your report. To do so, provide your sites within src/site/apt/ using the apt (almost plain text) format (see also here). Be careful, if you choose a name that is already chosen by a site plugin, the site plugin will be overridden with your content, e.g. "index.apt" will override the about-plugin index site.

You also have to add your sites to the menu as follow within the src/site/site.xml: (You can add a new menu or extend an existing one; the sitename must be equal to the apt-file name)

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/DECORATION/1.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">

        <publishDate position="left" format="E MMM dd HH:mm:ss z yyyy" />

        <body>
                <menu name="Custom Content">
                    <item name="Site Title" href="sitename.html"/>
                </menu>
                <menu ref="reports" />
        </body>
</project>

See also

• AppGuidelinesMain
• CSCO Java Entwicklungsumgebung
• AppHowToProjectSetup
• Sonatype Maven Reference

-- AndreasSchaller - 27 Nov 2014