Clarify instructions for "Process this rule at most (times)" specifically with "Match every build" #148
Description
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).