diff --git a/README.adoc b/README.adoc index 614f18a48..9bfb59afe 100644 --- a/README.adoc +++ b/README.adoc @@ -241,24 +241,15 @@ TIP: In the future, deprecated publishers should be replaced by https://plugins. NOTE: The detection of Maven builds requires using Maven 3.2+. -[cols="a,a,a,a,a",options="header",] -|=== -|Reporter -|Description -|Required Jenkins Plugin (1) -|Configuration to disable the feature + -Since v2.3.0 -|Marker file to disable the feature (2) - -|Generated Artifact -|Archiving and the fingerprinting of the artifacts and attached artifacts generated by the Maven build (jar, sources jar, javadocs jar...) -| -|`withMaven(options: [artifactsPublisher(disabled: true)],...)` -|`.skip-archive-generated-artifacts` +Generated Artifact:: +Archiving and the fingerprinting of the artifacts and attached artifacts generated by the Maven build (jar, sources jar, javadocs jar...) -|Generated JUnit reports -|Publishing of the JUnit reports generated from the http://maven.apache.org/surefire/maven-surefire-plugin/[Surefire], https://maven.apache.org/surefire/maven-failsafe-plugin/[FailSafe], https://www.eclipse.org/tycho/[Tycho], https://github.com/karma-runner/maven-karma-plugin[Karma] or https://github.com/eirslett/frontend-maven-plugin[Frontend] plugins during the Maven build. +Generated JUnit reports:: +Requires https://plugins.jenkins.io/junit/[Jenkins JUnit Plugin]. If the plugin is not installed, then the Maven report is ignored. ++ +Publishing of the JUnit reports generated from the http://maven.apache.org/surefire/maven-surefire-plugin/[Surefire], https://maven.apache.org/surefire/maven-failsafe-plugin/[FailSafe], https://www.eclipse.org/tycho/[Tycho], https://github.com/karma-runner/maven-karma-plugin[Karma] or https://github.com/eirslett/frontend-maven-plugin[Frontend] plugins during the Maven build. Except the Frontend one, all these plugins publish a `reportsDirectory` property which can be used to find and import JUnit compatible reports. The Frontend plugin has another behaviour, so for detection to work, you have to set a `REPORTS_DIRECTORY` environment variable to the plugin (and reuse it in your Karma configuration, to be consistent) : ++ ``` com.github.eirslett @@ -276,87 +267,115 @@ Except the Frontend one, all these plugins publish a `reportsDirectory` property ``` -|https://plugins.jenkins.io/junit/[Jenkins JUnit Plugin] +Generated Findbugs reports:: +Requires the deprecated https://plugins.jenkins.io/findbugs/[Jenkins FindBugs Plugin]. ++ +Publishing of the Findbugs reports generated by the Maven build + +Tasks scanner report:: +Requires the deprecated https://plugins.jenkins.io/tasks/[Jenkins Tasks Scanner Plugin] ++ +Publishing of a report of the "`FIXME`" and "`TODO`" tasks found in the java source code. The keywords can be configured. + + +Dependencies Fingerprinting (since 2.5.0):: +Fingerprint the Maven dependencies. By default, only the snapshot dependencies of scope compile, runtime and provided are fingerprinted. + +http://concordion.org/[Concordion] test report (since 3.0.0):: +Requires the https://plugins.jenkins.io/htmlpublisher/[Jenkins HTML Publisher Plugin] ++ +Publishing of the http://concordion.org/[Concordion] test reports. +Publish the Concordion reports generated by the `maven-surefire-plugin:test` and the `maven-failsafe-plugin:integration-test goals and located in the folder described by the system property `concordion.output.dir as documented in http://concordion.org/integrations/java/html/#maven[Concordion > Integration > Java > Maven] + +https://maven.apache.org/plugins/maven-invoker-plugin/[Maven Invoker Plugin] test reports:: +Requires the https://plugins.jenkins.io/maven-invoker-plugin/[Maven Invoker Plugin] ++ +Publish test reports generated by the https://maven.apache.org/plugins/maven-invoker-plugin/[maven-invoker-plugin:run] goal + +JGiven reports:: +Requires the https://plugins.jenkins.io/jgiven/[Jenkins JGiven Plugin] ++ +Publish http://jgiven.org/[JGiven] test reports + +JaCoCo Code Coverage:: +Requires the https://plugins.jenkins.io/jacoco/[Jenkins JaCoCo Plugin] ++ +Publish JaCoCo Code Coverage + +Maven Linker Publisher:: +Publish the Maven report on the pipeline build GUI (list of dependencies, produced artifacts, downstream & upstream pipelines). + +This publisher should be renamed "Maven Build Report Publisher". + +A reason to disable this publisher is typically to not "pollute" the build screen with Maven invocations when Maven is used as a utility (e.g. invocations of "maven-help-plugin:3.2.0:evaluate"...) + +Pipeline Graph Publisher:: +Build the graph of dependencies between Jenkins pipelines and Maven artifacts in order to trigger downstream pipelines (when using the `snapshotDependencies` on downstream pipelines) + +==== Implicit or Explicit activation of Publishers + +By default, all the publishers are enabled by default. + +It is possible to change the default activation of a publisher navigating to the `Global Tool Configuration` screen. + +It is possible to disable the default activation of publishers on a specific `withMaven(){...}` step using the `publisherStrategy='EXPLICIT'` attribute in the step `withMaven(publisherStrategy='EXPLICIT'){...}`. +The publishers can then be enabled explicitly in the `withMaven(){...}` step using the "publishers" attribute. + +It is possible to use a marker file to temporarily disable the feature for a specific Maven build. +Typically, used to disable a reporter for a specific build that would generate too much data for the default configuration of the reporter (e.g. too many generated artifacts...) or to workaround a bug in the "`withMaven`" waiting for a fix. +These markers file must be located in the home directory of the build. + + +[cols="a,a,a",options="header",] +|=== +|Reporter +|Configuration to disable the feature + +Since v2.3.0 +|Marker file to disable the feature + +|Generated Artifact +|`withMaven(options: [artifactsPublisher(disabled: true)],...)` +|`.skip-archive-generated-artifacts` + +|Generated JUnit reports |`withMaven(options: [junitPublisher(disabled: true)],...)` |`.skip-publish-junit-results` |Generated Findbugs reports -|Publishing of the Findbugs reports generated by the Maven build -|https://plugins.jenkins.io/findbugs/[Jenkins FindBugs Plugin] |`withMaven(options: [findbugsPublisher(disabled: true)],...)` |`.skip-publish-findbugs-results` |Tasks scanner report -|Publishing of a report of the "`FIXME`" and "`TODO`" tasks found in the java source code. The keywords can be configured. -|https://plugins.jenkins.io/tasks/[Jenkins Tasks Scanner Plugin] |`withMaven(options: [openTasksPublisher(disabled: true)],...)` |`.skip-task-scanner` -|Dependencies Fingerprinting + -(since 2.5.0) -|Fingerprint the Maven dependencies. + -By default, only the snapshot dependencies of scope compile, runtime and provided are fingerprinted. -| +|Dependencies Fingerprinting |`withMaven(options: [dependenciesFingerprintPublisher(disabled: true)],...)` |`.skip-fingerprint-maven-dependencies` -|http://concordion.org/[Concordion] test report + -(since 3.0.0) -|Publishing of the http://concordion.org/[Concordion] test reports. + -Publish the Concordion reports generated by the `maven-surefire-plugin:test` and the `maven-failsafe-plugin:integration-test goals and located in the folder described by the system property `concordion.output.dir as documented in http://concordion.org/integrations/java/html/#maven[Concordion > Integration > Java > Maven] -|https://plugins.jenkins.io/htmlpublisher/[Jenkins HTML Publisher Plugin] +|Concordion test report |`withMaven(options: [concordionPublisher(disabled: true)],...)`` |`.skip-publish-concordion-results` -|https://maven.apache.org/plugins/maven-invoker-plugin/[Maven Invoker Plugin] test reports -|Publish test reports generated by the https://maven.apache.org/plugins/maven-invoker-plugin/[maven-invoker-plugin:run] goal -|Maven Invoker Plugin +|Maven Invoker Plugin test reports |`withMaven(options: [invokerPublisher(disabled: true)],...)` |`.skip-publish-invoker-run` |JGiven reports -|Publish http://jgiven.org/[JGiven] test reports -|https://plugins.jenkins.io/jgiven/[Jenkins JGiven Plugin] |`withMaven(options: [jgivenPublisher(disabled: true)],...)` |`.skip-publish-jgiven-results` |JaCoCo Code Coverage -|Publish JaCoCo Code Coverage -|https://plugins.jenkins.io/jacoco/[Jenkins JaCoCo Plugin] -|withMaven(options: [jacocoPublisher(disabled: true)],...) +|`withMaven(options: [jacocoPublisher(disabled: true)],...)` | |Maven Linker Publisher -|Publish the Maven report on the pipeline build GUI (list of dependencies, produced artifacts, downstream & upstream pipelines). + -This publisher should be renamed "Maven Build Report Publisher". + -A reason to disable this publisher is typically to not "pollute" the build screen with Maven invocations when Maven is used as a utility (e.g. invocations of "maven-help-plugin:3.2.0:evaluate"...) -| |`withMaven(options: [mavenLinkerPublisher(disabled: true)],...)` |`skip-maven-linker-publisher` |Pipeline Graph Publisher -|Build the graph of dependencies between Jenkins pipelines and Maven artifacts in order to trigger downstream pipelines (when using the `snapshotDependencies` on downstream pipelines) -| |`withMaven(options: [pipelineGraphPublisher(disabled: true)],...)` |`.skip-pipeline-graph` |=== -(1) Jenkins Plugin to publish the reports on the Jenkins build page. -If the plugin is not installed, then the Maven report is ignored. - -(2) Marker file to temporarily disable the feature for a specific Maven build. -Typically, used to disable a reporter for a specific build that would generate too much data for the default configuration of the reporter (e.g. too many generated artifacts...) or to workaround a bug in the "`withMaven`" waiting for a fix. -These markers file must be located in the home directory of the build. - -==== Implicit or Explicit activation of Publishers - -By default, all the publishers are enabled by default. - -It is possible to change the default activation of a publisher navigating to the `Global Tool Configuration` screen. - -It is possible to disable the default activation of publishers on a specific `withMaven(){...}` step using the `publisherStrategy='EXPLICIT'` attribute in the step `withMaven(publisherStrategy='EXPLICIT'){...}`. -The publishers can then be enabled explicitly in the `withMaven(){...}` step using the "publishers" attribute. - [#feature-default-configuration] === Default Configuration