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.

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

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

Open
Eccenux opened this issue Nov 7, 2024 · 1 comment

Comments

@Eccenux
Copy link

Eccenux commented Nov 7, 2024

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
Copy link
Member

Eccenux added a commit to Eccenux/build-history-manager-plugin that referenced this issue Nov 12, 2024
Eccenux added a commit to Eccenux/build-history-manager-plugin that referenced this issue Nov 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants