gitlab-plugin icon indicating copy to clipboard operation
gitlab-plugin copied to clipboard

Add description of triggers to documentation and Freestyle job GUI

Open mtalexan opened this issue 2 years ago • 0 comments

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

Many of the fields in the Freestyle GUI don't have explanation and are non-obvious. There's even less explanation of most of these fields in the documentation, requiring digging up the jelly file to get figure out even the minimal association between the GUI descriptions and the fields, or digging thru the code to see how they're used.

Fields that definitely need explanation:

triggerOnPush: what context is this? Is this just the GitLab Push Event, or is there some filtering going on? Lots of existing Issues about when this is needed and doesn't seem to be.

triggerToBranchDeleteRequest: Not named consistently, but has absolutely no mention anywhere what this is.

triggerOnAcceptedMergeRequest: Not documented, and the "Accepted" terminology mismatches with the GitLab terminology of "Merged" as the state name of the merge request it's actually associated with. Does this require the triggerOnMergeRequest to also be set?

triggerOnClosedMergeRequest: Lots of bugs about this in the Issues, is there maybe an understanding gap and the triggerOnMergeRequest also needs to be set? There's no documentation on this.

triggerOnApprovedMergeRequest: No explanation, but has a warning in the GUI about needing the EE version of GitLab.

ciSkip: Not very well documented but has a great description in the GUI.

setBuildDescription: No explanation at all. What does this even do?

addNoteOnMergeRequest: No explanation, and might currently be broken. I'm not sure what it's supposed to do.

addCiMessage: No explanation. What is this?

addVoteOnMergeRequest: No explanation. Is supposed to add a thumbs up to MRs? Might be broken.

branchFilterName: Confusing if not using the Freestyle GUI, needs documentation about the relationship to branchFilterType.

branchFilterType: Mentioned, but almost no explanation. Freestyle GUI does a better job of explaining only if you can compare the jelly file to the actual GUI behavior.

sourceBranchRegex: jelly-only explanation, no documentation.

targetBranchRegex: jelly-only explanation, no documentation.

mergeRequestLabelFilterConfig: No explanation, and tougher to understand from jelly file.

pendingBuildName: no explanation.

A good GSoC first task for someone to learn the codebase from, as loosely discusssed in https://github.com/jenkinsci/gitlab-plugin/issues/1005

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

No response

mtalexan avatar May 22 '23 23:05 mtalexan