Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Reformat publisher documentation #348

Merged
merged 1 commit into from
Sep 9, 2021
Merged

Reformat publisher documentation #348

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
141 changes: 80 additions & 61 deletions README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) :
+
```
<plugin>
<groupId>com.github.eirslett</groupId>
Expand All @@ -276,87 +267,115 @@ Except the Frontend one, all these plugins publish a `reportsDirectory` property
</executions>
</plugin>
```
|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

Expand Down