From 950ac92cb160944c4f514e60ad96c884ef86a80d Mon Sep 17 00:00:00 2001 From: Kezhi Xiong Date: Sun, 21 Feb 2021 14:46:43 +0800 Subject: [PATCH] Add help docs --- README.md | 10 ++++++- .../checks/steps/PublishChecksStep.java | 29 ++++++++++++------- .../StepChecksAction/config.jelly | 16 ++++++++++ .../StepChecksAction/help-description.html | 3 ++ .../StepChecksAction/help-identifier.html | 5 ++++ .../StepChecksAction/help-label.html | 3 ++ .../steps/PublishChecksStep/config.jelly | 12 ++++++++ .../steps/PublishChecksStep/config.properties | 1 + 8 files changed, 68 insertions(+), 11 deletions(-) create mode 100644 src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/config.jelly create mode 100644 src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-description.html create mode 100644 src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-identifier.html create mode 100644 src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-label.html diff --git a/README.md b/README.md index 68764ab6..e2a436bd 100644 --- a/README.md +++ b/README.md @@ -38,9 +38,17 @@ If enabled, the statuses will be published in different stages of a Jenkins buil - publishChecks: you can publish checks directly in the pipeline script instead of depending on consumer plugins: ``` -publishChecks name: 'example', title: 'Pipeline Check', summary: 'check through pipeline', text: 'you can publish checks in pipeline script', detailsURL: 'https://github.com/jenkinsci/checks-api-plugin#pipeline-usage' +publishChecks name: 'example', title: 'Pipeline Check', summary: 'check through pipeline', + text: 'you can publish checks in pipeline script', + detailsURL: 'https://github.com/jenkinsci/checks-api-plugin#pipeline-usage', + actions: [[label:'an-user-request-action', description:'actions allow users to request pre-defined behaviours', identifier:'an unique identifier']] ``` +To use customized actions, you may need to define them on your own. +For instance, if you want to add GitHub checks actions which are basically buttons on the checks report, +you may need to extend [GHEventSubscriber](https://github.com/jenkinsci/github-plugin/blob/master/src/main/java/org/jenkinsci/plugins/github/extension/GHEventsSubscriber.java) to handle the user requests, +see [the handler](https://github.com/jenkinsci/github-checks-plugin/blob/ea060be67dad522ab6c31444fc4274955ac6e918/src/main/java/io/jenkins/plugins/checks/github/CheckRunGHEventSubscriber.java) for re-run requests as an example. + - withChecks: you can inject the check's name into the closure for other steps to use: ``` diff --git a/src/main/java/io/jenkins/plugins/checks/steps/PublishChecksStep.java b/src/main/java/io/jenkins/plugins/checks/steps/PublishChecksStep.java index 5ee76f3d..f886644f 100644 --- a/src/main/java/io/jenkins/plugins/checks/steps/PublishChecksStep.java +++ b/src/main/java/io/jenkins/plugins/checks/steps/PublishChecksStep.java @@ -3,8 +3,7 @@ import edu.hm.hafner.util.VisibleForTesting; import edu.umd.cs.findbugs.annotations.NonNull; import hudson.Extension; -import hudson.model.Run; -import hudson.model.TaskListener; +import hudson.model.*; import hudson.util.ListBoxModel; import io.jenkins.plugins.checks.api.*; import org.apache.commons.lang3.StringUtils; @@ -229,9 +228,11 @@ ChecksDetails extractChecksDetails() throws IOException, InterruptedException { /** * A simple wrapper for {@link ChecksAction} to allow users add checks actions by {@link PublishChecksStep}. */ - public static class StepChecksAction implements Serializable { + public static class StepChecksAction extends AbstractDescribableImpl implements Serializable { private static final long serialVersionUID = 1L; - private ChecksAction action; + private final String label; + private final String identifier; + private String description = StringUtils.EMPTY; /** * Creates an instance that wraps a newly constructed {@link ChecksAction} with according parameters. @@ -243,28 +244,36 @@ public static class StepChecksAction implements Serializable { */ @DataBoundConstructor public StepChecksAction(final String label, final String identifier) { - action = new ChecksAction(label, StringUtils.EMPTY, identifier); + this.label = label; + this.identifier = identifier; } @DataBoundSetter public void setDescription(final String description) { - action = new ChecksAction(getLabel(), description, getIdentifier()); + this.description = description; } public String getLabel() { - return action.getLabel().orElse(StringUtils.EMPTY); + return label; } public String getDescription() { - return action.getDescription().orElse(StringUtils.EMPTY); + return description; } public String getIdentifier() { - return action.getIdentifier().orElse(StringUtils.EMPTY); + return identifier; } public ChecksAction getAction() { - return action; + return new ChecksAction(label, description, identifier); + } + + /** + * Descriptor for {@link StepChecksAction}, required for Pipeline Snippet Generator. + */ + @Extension + public static class StepChecksActionDescriptor extends Descriptor { } } } diff --git a/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/config.jelly b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/config.jelly new file mode 100644 index 00000000..158216a6 --- /dev/null +++ b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/config.jelly @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-description.html b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-description.html new file mode 100644 index 00000000..192c9bf8 --- /dev/null +++ b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-description.html @@ -0,0 +1,3 @@ +
+ Detailed description for the action's purpose, functionality, and so on. +
\ No newline at end of file diff --git a/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-identifier.html b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-identifier.html new file mode 100644 index 00000000..eed71f8d --- /dev/null +++ b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-identifier.html @@ -0,0 +1,5 @@ +
+ The unique identifier for the action. Since for SCM platforms like GitHub, this is the only field that would be + sent back to your Jenkins instance when an action is requested, so you may need to use this field to bear more + information besides the basic type of the action. +
\ No newline at end of file diff --git a/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-label.html b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-label.html new file mode 100644 index 00000000..4f32e4cc --- /dev/null +++ b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-label.html @@ -0,0 +1,3 @@ +
+ The label to be displayed on the checks report for this action. +
diff --git a/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/config.jelly b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/config.jelly index 4930968a..da19de7f 100644 --- a/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/config.jelly +++ b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/config.jelly @@ -29,4 +29,16 @@ + +
+ + +
+ +
+ + +
+ + diff --git a/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/config.properties b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/config.properties index 1907e359..741e2164 100644 --- a/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/config.properties +++ b/src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/config.properties @@ -5,3 +5,4 @@ title.text=Text title.detailsURL=Details URL title.status=Status title.conclusion=Conclusion +title.actions=Actions