Add documentation to page: Jenkins, JaCoCo plugin

[Anton Thelander]

Hi,

Thank you so much for all the work you've done with Jenkins!!

I’m working with Jenkins.

In Jenkins, the JaCoCo plugin, I decided to find out what the difference was between for example

minimumBranchCoverage

maximumBranchCoverage

But I couldn’t find it here

https://www.jenkins.io/doc/pipeline/steps/jacoco/

And I Googled some to find information elsewhere about it but it was hard to find.

 

But I found this

https://stackoverflow.com/a/57071681/6533028

With this note

"If a coverage is below minimum the build fails, if the coverage is below maximum the build is unstable, if it is above then it is a success."

So then, in order for it to be easier to understand the difference between minimum and maximum, please add a note like the note just above or similar to this page

https://www.jenkins.io/doc/pipeline/steps/jacoco/

 

Thank you!!

Anton Thelander

Software Developer

Sundsvall, Sweden

[Mark Waite]

Thanks for doing that research and thanks for sharing the results of the research.

We're hosting Docs office hours twice a week (Monday at 23:00 UTC and Thursday at 18:00 UTC).  We'll use this example in our office hours next Monday to show how to add online help to a Pipeline step.  Adding documentation to a pipeline step is different than adding documentation to the www.jenkins.io site.  It requires submitting a change to the plugin that implements the step, rather than to the www.jenkins.io site.  We'll demonstrate how it is done next week.

Thanks again,

Mark Waite

--
You received this message because you are subscribed to the Google Groups "Jenkins Documentation" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-doc...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-docs/60205820-d142-410f-ad4a-af1f8423f557n%40googlegroups.com.

[Anton Thelander]

Thank you very much for that information!

Thank you

Anton

[Anton Thelander]

Hi again,

I thought that you'd demonstrate for you guys and that you guys' fix it but maybe you wanted me to be in on this meeting that was yesterday, Monday at 23:00 UTC.

I read that the Docs are updated by volunteers.

But you didn't send a link to a meeting for me to join so I guessed you'd demonstrate and fix it there in the Office Hours.

Was I wrong?

/Anton

[Mark Waite]

On Tuesday, February 16, 2021 at 7:02:43 AM UTC-7 anton wrote:

Hi again,

I thought that you'd demonstrate for you guys and that you guys' fix it but maybe you wanted me to be in on this meeting that was yesterday, Monday at 23:00 UTC.

I read that the Docs are updated by volunteers.

But you didn't send a link to a meeting for me to join so I guessed you'd demonstrate and fix it there in the Office Hours.

Was I wrong?

You were correct in almost all of those items.  Docs are maintained by volunteers.  We didn't expect that you would attend (though you're certainly welcome to attend).  We met in office hours yesterday as listed on the Jenkins calendar (meeting link is on the Jenkins calendar).  We spent most of the session exploring the best techniques to fix the problem.  It was a fun and interesting session.  Thanks for asking the question!  The session was recorded, though the recording has not been published yet.  That will likely happen today.

We concluded that the jacoco plugin uses tables to define the coverage limits in a nicely recognized format.  That format works very well for the user defining limits interactively.  That format provides online help available for some plugin settings.  Unfortunately, that nicely recognized format does not allow easy viewing of online help for individual fields (like the fields you noted are missing documentation).  The individual fields are fields within a table and Jenkins has no facility to associate online help with a field in a table.

We decided that the best approach in this case is to add online help summarizing the various fields on one or more of the overview checkboxes (Either "Change build status according the thresholds" or "Always run coverage collection, even if build is FAILED or ABORTED").  That will allow users of the Pipeline Syntax snippet generator to see the help from the Jenkins UI.

In addition to that summary on the overview checkboxes, each individual field needs a description of its values so that it will appear in the pipeline steps reference page for the jacoco step.  I started the local changes for the jacoco plugin to provide that online help.  Additional changes will be needed.  Once I've completed those changes, I'll submit the changes as a jacoco plugin pull request.  The maintainer of the jacoco plugin will then need to review the changes and merge them once review is complete.  Once merged, the next jacoco plugin release will include that online help and the next pipeline steps reference update after that release will include the updated documentation as well.  The end result will be better online help for jacoco plugin users and better argument descriptions in the jacoco pipeline step reference.

Office hours also found that the Jenkins base version required by the jacoco plugin is old enough that the development experience is more difficult for pipeline help development.  We decided that it will be best if we create a new recording of the process for a final description that shows how to update pipeline online help within a plugin.  That will provide a simpler experience for contributors viewing the video and reading the documentation.

Thanks again for your suggestions.
Mark Waite

 

/Anton

torsdag 11 februari 2021 kl. 11:41:17 UTC+1 skrev Anton Thelander:

Thank you very much for that information!

Thank you

Anton

onsdag 10 februari 2021 kl. 14:53:22 UTC+1 skrev Mark Waite:

Thanks for doing that research and thanks for sharing the results of the research.

We're hosting Docs office hours twice a week (Monday at 23:00 UTC and Thursday at 18:00 UTC).  We'll use this example in our office hours next Monday to show how to add online help to a Pipeline step.  Adding documentation to a pipeline step is different than adding documentation to the www.jenkins.io site.  It requires submitting a change to the plugin that implements the step, rather than to the www.jenkins.io site.  We'll demonstrate how it is done next week.

Thanks again,

Mark Waite

[Mark Waite]

I've submitted https://github.com/jenkinsci/jacoco-plugin/pull/141 as the pull request to improve the jacoco plugin pipeline documentation.

[Anton Thelander]

Okay okay! Thank you!! Alright, you met, nice nice. Okay, then I know your procedure there in the session.

Nice that you collectively still decided to add online help for this.

I see that the pull request has been merged. Thank you very much that you went out of the way to fix this yourself Mark :)

Okay okay, thank you for that you in Office hours also decided to create a new recording for the process on how to update pipeline online help.

Yeah, I saw the PR and that it's merged, thank you!

/Anton

[Mark Waite]

The online help within the Jenkins user interface is still missing a visible description of the meaning of the values for each of the columns.  That description should explain the various fields so that a user in the Jenkins configuration page can understand the difference between "branch" and "instruction" coverage.  That will need to wait for another pull request, since it will require more research before I can confidently describe those differences.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-docs/7aeb6630-b130-4330-a42e-e5ab55daee07n%40googlegroups.com.

[Anton Thelander]

Okay! Alright alright! Thank you. I'd say "branch" coverage is generally the different executions/evaluations of if/else if/else statements and "instruction" coverage is kind of like row for row coverage.

[Mark Waite]

Agreed, though I suspect the JaCoCo project has some precise phrasing for the meaning of those terms and we'd help users if we used the same descriptive phrasing in our online help as the JaCoCo project uses in their documentation.  Just haven't had the time to do that research yet.

Thanks!

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-docs/83c7458e-a1e9-47e8-b7b9-d0751a79afc2n%40googlegroups.com.