jenkinsci / build-history-manager-plugin

Jenkins plugin that allows to define which builds should be removed and which preserved. Several decision factors such as date, number or result can be taken into account
https://plugins.jenkins.io/build-history-manager/
MIT License
5 stars 11 forks source link

Clarify instructions for "Process this rule at most (times)" specifically with "Match every build" #148

Open Eccenux opened 3 weeks ago

Eccenux commented 3 weeks ago

Describe your use-case which is not covered by existing documentation.

I wanted to keep 5 builds of any kind and it wasn't really clear to me how to do that.

Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration.

I think de description for "Process this rule at most (times)" is a bit misleading:

If the value is set to 1..n, once the value is reached, the rule is effectively disabled and is no longer applied.

My thinking was: so I will run 5 builds and the rule will be disabled. That is not the case though. I think it would be helpful to rephrase it and provide a pseudo code of what happens.

Are you interested in contributing to the documentation?

For "Process this rule at most (times)". Change the help to:

## Description

The rule will stop being processed after a certain number of matched builds.
Once this condition is met, only the other rules will continue to be processed.

Internally and in the documentation, this value is called `matchAtMost`.

There are some special values:
   - If `matchAtMost = -1`, there is no limitation; all builds will be evaluated.
   - If `matchAtMost = 0`, no builds will be evaluated. This disables the rule, as it will not apply to any build.
   - If `matchAtMost > 0`, this rule will only be applied `matchAtMost` times 
     in each build history manager process (in each loop over builds after a build).

## Use cases

This feature provides the option to control the number of builds the rule can process.
If used with specific actions it can save a significant amount of time when the build history is long.

This feature also provides the option to skip a number of builds while processing builds. 
To skip 5 builds, you should create a rule with the "Match every build" condition and no action, then set `matchAtMost = 5`.
This will effectively skip 5 builds in each build history manager process. It’s equivalent to saying `buildToCheck = lastBuildNo - 5`.

## Warning!
<unchanged>

Making it clear that the build history manager process is a loop and rules are applied each time after a build was crucial for my understanding of the plugin.

I think it also helps to show how fields map to variables also in the contextual help of form fields (not only in the main documentation).

damianszczepanik commented 3 weeks ago

Would you prepare updated https://github.com/jenkinsci/build-history-manager-plugin/blob/master/src/main/resources/pl/damianszczepanik/jenkins/buildhistorymanager/model/Rule/help-matchAtMost.html as pull request that can be merged into the project ?