{"id":23282778,"url":"https://github.com/itsallcode/openfasttrace-maven-plugin","last_synced_at":"2025-08-21T13:33:44.509Z","repository":{"id":40442532,"uuid":"161908694","full_name":"itsallcode/openfasttrace-maven-plugin","owner":"itsallcode","description":"Maven Plugin for OpenFastTrace (https://github.com/itsallcode/openfasttrace)","archived":false,"fork":false,"pushed_at":"2024-11-13T05:29:46.000Z","size":201,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-13T06:24:10.640Z","etag":null,"topics":["java","maven-plugin","openfasttrace","quality-assurance","requirements-management","requirements-tracing","software-engineering"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itsallcode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-15T13:41:55.000Z","updated_at":"2024-09-06T15:06:46.000Z","dependencies_parsed_at":"2023-12-02T07:30:39.991Z","dependency_job_id":"a378b494-19e2-408c-9828-92e7c16d94b2","html_url":"https://github.com/itsallcode/openfasttrace-maven-plugin","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsallcode%2Fopenfasttrace-maven-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsallcode%2Fopenfasttrace-maven-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsallcode%2Fopenfasttrace-maven-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsallcode%2Fopenfasttrace-maven-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsallcode","download_url":"https://codeload.github.com/itsallcode/openfasttrace-maven-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230519247,"owners_count":18238847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","maven-plugin","openfasttrace","quality-assurance","requirements-management","requirements-tracing","software-engineering"],"created_at":"2024-12-20T00:29:47.073Z","updated_at":"2024-12-20T00:29:47.644Z","avatar_url":"https://github.com/itsallcode.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# openfasttrace-maven-plugin\n\nMaven Plugin for [OpenFastTrace](https://github.com/itsallcode/openfasttrace) (OFT).\n\n## Project Information\n\n[![Build](https://github.com/itsallcode/openfasttrace-maven-plugin/actions/workflows/build.yml/badge.svg)](https://github.com/itsallcode/openfasttrace-maven-plugin/actions/workflows/build.yml)\n[![Maven Central](https://img.shields.io/maven-central/v/org.itsallcode/openfasttrace-maven-plugin.svg?label=Maven%20Central)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.itsallcode%22%20a%3A%22openfasttrace-maven-plugin%22)\n\nSonarcloud status:\n\n[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=bugs)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n[![Code smells](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=code_smells)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n[![Duplicated Lines](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=ncloc)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=reliability_rating)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=security_rating)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n[![Technical Dept](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=sqale_index)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace-maven-plugin\u0026metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin)\n\n* [Blog](https://blog.itsallcode.org/)\n* [Changelog](CHANGELOG.md)\n* [Contributing guide](CONTRIBUTING.md)\n* [OpenFastTrace stories](https://github.com/itsallcode/openfasttrace/wiki/OFT-Stories)\n\n## Usage\n\nAdd the openfasttrace-maven-plugin to your `pom.xml`:\n\n```xml\n\u003cplugin\u003e\n    \u003cgroupId\u003eorg.itsallcode\u003c/groupId\u003e\n    \u003cartifactId\u003eopenfasttrace-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e2.3.0\u003c/version\u003e\n    \u003cexecutions\u003e\n        \u003cexecution\u003e\n            \u003cid\u003etrace-requirements\u003c/id\u003e\n            \u003cgoals\u003e\n                \u003cgoal\u003etrace\u003c/goal\u003e\n            \u003c/goals\u003e\n        \u003c/execution\u003e\n    \u003c/executions\u003e\n    \u003cconfiguration\u003e\n        \u003cfailBuild\u003etrue\u003c/failBuild\u003e\n        \u003creportOutputFormat\u003ehtml\u003c/reportOutputFormat\u003e\n        \u003creportVerbosity\u003eALL\u003c/reportVerbosity\u003e\n        \u003creportShowOrigin\u003etrue\u003c/reportShowOrigin\u003e\n        \u003cdetailsSectionDisplay\u003eCOLLAPSE\u003c/detailsSectionDisplay\u003e\n        \u003cartifactTypes\u003efeat,req\u003c/artifactTypes\u003e\n        \u003ctags\u003eprototype,mvp\u003c/tags\u003e\n    \u003c/configuration\u003e\n\u003c/plugin\u003e\n```\n\nThen you can run tracing by calling the goal directly: `mvn openfasttrace:trace`.\n\nThe plugin binds to the `verify` lifecycle, so you can also use `mvn verify`.\n\nSee [src/test/resources/empty-project](src/test/resources/simple-project/) for an example project.\n\n### OpenFastTrace Plugins\n\nYou can use OpenFastTrace plugins to import and export requirements in additional formats. Include plugins by adding them as a dependency to the `openfasttrace-maven-plugin`, see [project-with-plugins](./src/test/resources/project-with-plugins) as an example.\n\n```xml\n\u003cplugin\u003e\n    \u003cgroupId\u003eorg.itsallcode\u003c/groupId\u003e\n    \u003cartifactId\u003eopenfasttrace-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e2.3.0\u003c/version\u003e\n    \u003cconfiguration\u003e\n        \u003cfailBuild\u003etrue\u003c/failBuild\u003e\n    \u003c/configuration\u003e\n    \u003cdependencies\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003eorg.itsallcode\u003c/groupId\u003e\n            \u003cartifactId\u003eopenfasttrace-asciidoc-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e0.2.0\u003c/version\u003e\n        \u003c/dependency\u003e\n    \u003c/dependencies\u003e\n\u003c/plugin\u003e\n```\n\n### Configuration\n\nYou can configure the plugin using the `\u003cconfiguration\u003e` element.\n\n#### Traced Directories\n\nBy default the OFT plugin imports requirements from the following directories:\n\n* The `doc` sub-directory of the module that includes the plugin if it exists\n* For each Maven module in the project if they exist:\n  * Compile source roots (default: `src/main/java`)\n  * Resources (default: `src/main/resources`)\n  * Test compile source roots (default: `src/test/java`)\n  * Test resources (default: `src/test/resources`)\n\n##### Adding Custom Source Directories\n\nYou can add additional custom source directories using the [Build Helper Maven Plugin](https://www.mojohaus.org/build-helper-maven-plugin/).\n\nPlease note that the phases `generate-sources` and `generate-test-sources` have nothing to do with the phase in which OFT does its job, rather it defines in which phase the directory is added to the list of known source directories by the `build-helper-maven-plugin`.\n\nThe following snipped adds source directory `src/main/rust` and test source directory `src/test/rust`:\n\n```xml\n\u003cplugin\u003e\n    \u003cgroupId\u003eorg.codehaus.mojo\u003c/groupId\u003e\n    \u003cartifactId\u003ebuild-helper-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e3.6.0\u003c/version\u003e\n    \u003cexecutions\u003e\n        \u003cexecution\u003e\n            \u003cid\u003eadd-source\u003c/id\u003e\n            \u003cphase\u003egenerate-sources\u003c/phase\u003e\n            \u003cgoals\u003e\n                \u003cgoal\u003eadd-source\u003c/goal\u003e\n            \u003c/goals\u003e\n            \u003cconfiguration\u003e\n                \u003csources\u003e\n                    \u003csource\u003esrc/main/rust\u003c/source\u003e\n                \u003c/sources\u003e\n            \u003c/configuration\u003e\n        \u003c/execution\u003e\n        \u003cexecution\u003e\n            \u003cid\u003eadd-test-source\u003c/id\u003e\n            \u003cphase\u003egenerate-test-sources\u003c/phase\u003e\n            \u003cgoals\u003e\n                \u003cgoal\u003eadd-test-source\u003c/goal\u003e\n            \u003c/goals\u003e\n            \u003cconfiguration\u003e\n                \u003csources\u003e\n                    \u003csource\u003esrc/test/rust\u003c/source\u003e\n                \u003c/sources\u003e\n            \u003c/configuration\u003e\n        \u003c/execution\u003e\n    \u003c/executions\u003e\n\u003c/plugin\u003e\n```\n\n##### Adding Custom Resource Directories\n\nYou can add additional resource directories using the [Maven Resources Plugin](https://maven.apache.org/plugins/maven-resources-plugin/examples/resource-directory.html). The following snipped adds `src/custom-resources` as additional resource directory:\n\n```xml\n\u003cbuild\u003e\n    \u003cresources\u003e\n        \u003cresource\u003e\n            \u003cdirectory\u003esrc/custom-resources\u003c/directory\u003e\n        \u003c/resource\u003e\n    \u003c/resources\u003e\n\u003c/build\u003e\n```\n\n#### Selecting the Imported Specification Items\n\nSometimes you don't want to trace the whole requirement chain. Instead, you are interested in the consistency of a subset. For instance, if you need to deliver a system requirement specification to another team, your job is to assure that the document is consistent in itself.\n\nFor those cases you can add an include list to the configuration that explicitly lists all artifact types or tags to be imported. Note that this also affects which required coverage is imported — which is exactly what you want in this situation.\n\nSee the [OFT user guide on import options](https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md#import-options) for details.\n\n##### Select Artifact Types\n\nThe following example configuration limits import to artifact types `feat` and `req`.\n\n```xml\n\u003cconfiguration\u003e\n    \u003cartifactTypes\u003efeat,req\u003c/artifactTypes\u003e\n\u003c/configuration\u003e\n```\n\nThis works similar to OFT's command line argument `--wanted-artifact-types`.\n\n##### Select Tags\n\nThe following example configuration limits import to tags `prototype` and `mvp`.\n\n```xml\n\u003cconfiguration\u003e\n    \u003ctags\u003eprototype,mvp\u003c/tags\u003e\n\u003c/configuration\u003e\n```\n\nThis works similar to OFT's command line argument `--wanted-tags`.\n\nYou can specify the underscore `_` to import specification items without tags.\n\nYou can also specify the tags to import using CLI option `-Dtags=prototype,mvp`.\n\n#### Report\n\n##### Report Format\n\nThe tracing report is in HTML format by default. You can configure plain text format with `\u003creportOutputFormat\u003eplain\u003c/reportOutputFormat\u003e`.\n\n##### Report Location\n\nThe tracing report will be written to `target/tracing-report.html` by default. You can configure the location with `\u003coutputDirectory\u003e${project.build.directory}/reports/\u003c/outputDirectory\u003e`.\n\n##### HTML Report Details Section Display\n\nThe HTML report will have its details sections collapsed (i.e. hidden) by default. You can render the HTML with expanded details sections with `\u003cdetailsSectionDisplay\u003eEXPAND\u003c/detailsSectionDisplay\u003e`.\n\n#### Fail Build\n\nBy default the build will fail when there are errors found during tracing. To continue with the build when tracing fails, use configuration `\u003cfailBuild\u003efalse\u003c/failBuild\u003e`.\n\n#### Skipping Execution\n\nTo skip execution of the plugin, add command line option `-Dopenfasttrace.skip=true` when running Maven.\n\n## Development\n\n### Installation of Initial Build Dependencies on Linux\n\n#### Ubuntu or Debian\n\nIf you want to build OFT:\n\n```sh\napt-get install openjdk-17-jdk maven\n```\n\n### Configure Maven Toolchain\n\nThis project uses Maven Toolchains to configure the correct JDK version (see the [documentation](https://maven.apache.org/guides/mini/guide-using-toolchains.html) for details). To configure the Toolchains plugin create file ` ~/.m2/toolchains.xml` with the following content. Adapt the paths to your JDKs.\n\n```xml\n\u003ctoolchains xmlns=\"http://maven.apache.org/TOOLCHAINS/1.1.0\"\n    xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n    xsi:schemaLocation=\"http://maven.apache.org/TOOLCHAINS/1.1.0 http://maven.apache.org/xsd/toolchains-1.1.0.xsd\"\u003e\n    \u003ctoolchain\u003e\n        \u003ctype\u003ejdk\u003c/type\u003e\n        \u003cprovides\u003e\n            \u003cversion\u003e17\u003c/version\u003e\n        \u003c/provides\u003e\n        \u003cconfiguration\u003e\n            \u003cjdkHome\u003e/usr/lib/jvm/java-17-openjdk-amd64/\u003c/jdkHome\u003e\n        \u003c/configuration\u003e\n    \u003c/toolchain\u003e\n        \u003ctoolchain\u003e\n        \u003ctype\u003ejdk\u003c/type\u003e\n        \u003cprovides\u003e\n            \u003cversion\u003e21\u003c/version\u003e\n        \u003c/provides\u003e\n        \u003cconfiguration\u003e\n            \u003cjdkHome\u003e/usr/lib/jvm/java-21-openjdk-amd64/\u003c/jdkHome\u003e\n        \u003c/configuration\u003e\n    \u003c/toolchain\u003e\n\u003c/toolchains\u003e\n```\n\n### Essential Build Steps\n\n* `git clone https://github.com/itsallcode/openfasttrace-maven-plugin.git`\n* Run `mvn test` to run unit tests.\n* Run `mvn integration-test` to run integration tests.\n\n### Using Eclipse\n\nImport as a Maven project using *\"File\" \u0026rarr; \"Import...\" \u0026rarr; \"Maven\" \u0026rarr; \"Existing Maven Projects\"*\n\n### Run local sonar analysis\n\n```sh\nsonar_token=\"[token]\"\nmvn clean org.jacoco:jacoco-maven-plugin:prepare-agent package sonar:sonar \\\n    -Dsonar.login=$sonar_token\n```\n\nSee analysis results at https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin\n\n### Check for updated dependencies / plugins\n\nDisplay dependencies and plugins with newer versions:\n\n```sh\nmvn --update-snapshots versions:display-dependency-updates versions:display-plugin-updates\n```\n\nAutomatically upgrade dependencies:\n\n```sh\nmvn --update-snapshots versions:use-latest-releases versions:update-properties\n```\n\n### Creating a Release on Maven Central and GitHub\n\n#### Prepare the Release\n\n1. Checkout the `main` branch.\n2. Update version in `pom.xml`, `CHANGELOG.md` and `README.md`.\n3. Commit and push changes.\n4. Create a new pull request, have it reviewed and merged to `main`.\n\n### Perform the Release\n\n1. Start the release workflow\n  * Run command `gh workflow run release.yml --repo itsallcode/openfasttrace-maven-plugin --ref main`\n  * or go to [GitHub Actions](https://github.com/itsallcode/openfasttrace-maven-plugin/actions/workflows/release.yml) and start the `release.yml` workflow on branch `main`.\n2. Update title and description of the newly created [GitHub release](https://github.com/itsallcode/openfasttrace-maven-plugin/releases).\n3. After some time the release will be available at [Maven Central](https://repo1.maven.org/maven2/org/itsallcode/openfasttrace-maven-plugin/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsallcode%2Fopenfasttrace-maven-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsallcode%2Fopenfasttrace-maven-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsallcode%2Fopenfasttrace-maven-plugin/lists"}