Skip to content
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time

OpenFastTrace Developer Guide

This document contains technical information for developers contributing to OpenFastTrace (short OFT).

If you want to know more about how to contribute to OFT, please check out our Contributor Guide.

Getting the OpenFastTrace Library

Getting OFT via Maven

To use OpenFastTrace as a dependency in your Maven project add this to your pom.xml:

<dependencies>
    <dependency>
        <groupId>org.itsallcode.openfasttrace</groupId>
        <artifactId>openfasttrace</artifactId>
        <version>2.3.5</version>
        <scope>compile</scope>
    </dependency>
</dependencies>

Getting OFT via Gradle

To use OpenFastTrace as a dependency in your Gradle project:

dependencies {
    compile "org.itsallcode.openfasttrace:openfasttrace:2.3.5"
}

Build Time Dependencies

The list below shows all build time dependencies in alphabetical order. Note that except the Maven build tool all required modules are downloaded automatically by Maven.

Dependency Purpose License
Apache Maven Build tool Apache License 2.0
Equals Verifier Automatic contract checker for equals() and hash() Apache License 2.0
Hamcrest Auto Matcher Speed-up for building Hamcrest matchers GNU General Public License V3
JUnit Unit testing framework Eclipse Public License 1.0
Mockito Mocking framework MIT License
JUnit5 System Extensions JUnit extension for testing System.x calls Eclipse Public License 2.0
Pitest Mutation testing Apache License 2.0

Preparations

OpenFastTrace uses Apache Maven as technical project management tool that resolves and downloads the build-dependencies before building the packages.

Installation of Initial Build Dependencies on Linux

Ubuntu or Debian

If you want to build OFT:

apt-get install openjdk-11-jdk maven

Essential Build Steps

  • git clone https://github.com/itsallcode/openfasttrace.git
  • Run mvn test to run unit tests.
  • Run mvn exec:java@trace to run requirements tracing.

Using Eclipse

Import as a Maven project using "File" → "Import..." → "Maven" → "Existing Maven Projects"

Configure Logging

We use java.util.logging for logging. To configure log level and formatting, add the following system property:

-Djava.util.logging.config.file=src/test/resources/logging.properties

License File Header

  • We use license-maven-plugin to check in verify phase that all files have the correct license header. The build will fail if there are any files with missing/outdated headers.
  • To update files with correct license headers and generate file LICENSE.txt, run command
mvn license:update-file-header

Check for updated dependencies / plugins

mvn versions:display-dependency-updates
mvn versions:display-plugin-updates

Run local sonar analysis

mvn clean org.jacoco:jacoco-maven-plugin:prepare-agent package sonar:sonar \
    -Dsonar.host.url=https://sonarcloud.io \
    -Dsonar.organization=itsallcode \
    -Dsonar.login=[token]

See analysis results at https://sonarcloud.io/dashboard?id=org.itsallcode.openfasttrace%3Aopenfasttrace

Run mutation testing

mvn org.pitest:pitest-maven:mutationCoverage
# speed up repeated analysis with history
mvn -DwithHistory org.pitest:pitest-maven:mutationCoverage

Publishing to JCenter


NOTE

This currently only works for release version numbers, not SNAPSHOT versions.


  1. Add the following to your ~/.m2/settings.xml:

    <servers>
        <server>
            <id>itsallcode-maven-repo</id>
            <username>[bintray-username]</username>
            <password>[bintray-api-key]</password>
        </server>
        <server>
            <id>itsallcode-maven-repo-snapshots</id>
            <username>[bintray-username]</username>
            <password>[bintray-api-key]</password>
        </server>
    </servers>
  2. Checkout the develop branch.

  3. Update version in openfasttrace-parent/pom.xml (revision property), README.md and doc/developer_guide.md.

  4. Add changes in new version to CHANGELOG.md.

  5. Commit and push changes

  6. Run this command (will take up to 10 minutes)

    mvn clean deploy
  7. Merge to master branch

  8. Create a release of the master branch on GitHub.

  9. Upload product/target/openfasttrace-<version>.jar and attach it to the new GitHub release.

  10. Sign in at bintray.com

  11. Go to the Bintray project page

  12. There should be a notice saying "You have 176 unpublished item(s) for this package". Click the "Publish" link. Binaries will be available for download at JCenter. This will take a few minutes.

  13. Publish to Maven Central by clicking the "Sync" button at https://bintray.com/itsallcode/itsallcode/openfasttrace#central. After some time the new version will appear at Maven Central.