From 0303d9baab46ecc8b4817f2719e1f9a669a3e751 Mon Sep 17 00:00:00 2001 From: Alejandra Ferreiro Vidal Date: Fri, 29 Mar 2019 12:46:25 +0100 Subject: [PATCH] githubPublishRelease: generate docu --- .../docs/steps/githubPublishRelease.md | 69 ++----------------- vars/githubPublishRelease.groovy | 61 +++++++++++++--- 2 files changed, 56 insertions(+), 74 deletions(-) diff --git a/documentation/docs/steps/githubPublishRelease.md b/documentation/docs/steps/githubPublishRelease.md index 9bdcf5fa2..304eccce0 100644 --- a/documentation/docs/steps/githubPublishRelease.md +++ b/documentation/docs/steps/githubPublishRelease.md @@ -1,18 +1,6 @@ -# githubPublishRelease +# ${docGenStepName} -## Description - -This step creates a tag in your GitHub repository together with a release. - -The release can be filled with text plus additional information like: - -* Closed pull request since last release -* Closed issues since last release -* link to delta information showing all commits since last release - -The result looks like - -![Example release](../images/githubRelease.png) +## ${docGenDescription} ## Prerequisites @@ -20,6 +8,10 @@ You need to create a personal access token within GitHub and add this to the Jen Please see [GitHub documentation for details about creating the personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). +## ${docGenParameters} + +## ${docGenConfiguration} + ## Example Usage of pipeline step: @@ -27,52 +19,3 @@ Usage of pipeline step: ```groovy githubPublishRelease script: this, releaseBodyHeader: "**This is the latest success!**
" ``` - -## Parameters - -| parameter | mandatory | default | possible values | -| ----------|-----------|---------|-----------------| -|script|yes||| -|addClosedIssues|no|`false`|| -|addDeltaToLastRelease|no|`false`|| -|customFilterExtension|no|``|| -|excludeLabels|no||| -|githubApiUrl|no|`//https://api.github.com`|| -|githubOrg|yes|`script.commonPipelineEnvironment.getGitFolder()`|| -|githubRepo|yes|`script.commonPipelineEnvironment.getGitRepo()`|| -|githubServerUrl|no|`https://github.com`|| -|githubTokenCredentialsId|yes||| -|releaseBodyHeader|no||| -|version|yes|`script.commonPipelineEnvironment.getArtifactVersion()`|| - -### Details - -* `script` defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration. -* All GitHub related properties allow you to overwrite the default behavior of identifying e.g. GitHub organization, GitHub repository. -* `version` defines the version number which will be written as tag as well as release name -* By defining the `releaseBodyHeader` you can specify the content which will appear for the release -* If you set `addClosedIssues` to `true`, a list of all closed issues and merged pull-requests since the last release will added below the `releaseBodyHeader` -* If you set `addDeltaToLastRelease` to `true`, a link will be added to the relese information that brings up all commits since the last release. -* By passing the parameter `customFilterExtension` it is possible to pass additional filter criteria for retrieving closed issues since the last release. Additional criteria could be for example specific `label`, or `filter` according to [GitHub API documentation](https://developer.github.com/v3/issues/). -* It is possible to exclude issues with dedicated labels using parameter `excludeLabels`. Usage is like `excludeLabels: ['label1', 'label2']` - -## Step configuration - -We recommend to define values of step parameters via [config.yml file](../configuration.md). - -In following sections the configuration is possible: - -| parameter | general | step | stage | -| ----------|-----------|---------|-----------------| -|script|||| -|addClosedIssues||X|X| -|addDeltaToLastRelease||X|X| -|customFilterExtension||X|X| -|excludeLabels||X|X| -|githubApiUrl|X|X|X| -|githubOrg||X|X| -|githubRepo||X|X| -|githubServerUrl|X|X|X| -|githubTokenCredentialsId|X|X|X| -|releaseBodyHeader||X|X| -|version||X|X| diff --git a/vars/githubPublishRelease.groovy b/vars/githubPublishRelease.groovy index 2ec89bb3c..bac7850e0 100644 --- a/vars/githubPublishRelease.groovy +++ b/vars/githubPublishRelease.groovy @@ -1,27 +1,66 @@ import static com.sap.piper.Prerequisites.checkScript +import com.sap.piper.GenerateDocumentation import com.sap.piper.Utils import com.sap.piper.ConfigurationHelper import groovy.transform.Field @Field String STEP_NAME = getClass().getName() -@Field Set GENERAL_CONFIG_KEYS = ['githubApiUrl', 'githubTokenCredentialsId', 'githubServerUrl'] -@Field Set STEP_CONFIG_KEYS = [ - 'addClosedIssues', - 'addDeltaToLastRelease', - 'customFilterExtension', - 'excludeLabels', + +@Field Set GENERAL_CONFIG_KEYS = [ + /** Allows to overwrite the GitHub API url.*/ 'githubApiUrl', + /** + * Allows to overwrite the GitHub token credentials id. + * @possibleValues Jenkins credential id + */ 'githubTokenCredentialsId', - 'githubOrg', - 'githubRepo', - 'githubServerUrl', - 'releaseBodyHeader', - 'version' + /** Allows to overwrite the GitHub url.*/ + 'githubServerUrl' ] + +@Field Set STEP_CONFIG_KEYS = GENERAL_CONFIG_KEYS.plus([ + /** + * If it is set to `true`, a list of all closed issues and merged pull-requests since the last release will added below the `releaseBodyHeader`. + * @possibleValues `true`, `false` + */ + 'addClosedIssues', + /** + * If you set `addDeltaToLastRelease` to `true`, a link will be added to the relese information that brings up all commits since the last release. + * @possibleValues `true`, `false` + */ + 'addDeltaToLastRelease', + /** Allows to pass additional filter criteria for retrieving closed issues since the last release. Additional criteria could be for example specific `label`, or `filter` according to [GitHub API documentation](https://developer.github.com/v3/issues/).*/ + 'customFilterExtension', + /** Allows to exclude issues with dedicated labels. Usage is like `excludeLabels: ['label1', 'label2']`.*/ + 'excludeLabels', + /** Allows to overwrite the GitHub organitation.*/ + 'githubOrg', + /** Allows to overwrite the GitHub repository.*/ + 'githubRepo', + /** Allows to specify the content which will appear for the release.*/ + 'releaseBodyHeader', + /** Defines the version number which will be written as tag as well as release name.*/ + 'version' +]) + @Field Set PARAMETER_KEYS = STEP_CONFIG_KEYS +/** + * This step creates a tag in your GitHub repository together with a release. + * + * The release can be filled with text plus additional information like: + * + * * Closed pull request since last release + * * Closed issues since last release + * * link to delta information showing all commits since last release + * + * The result looks like + * + * ![Example release](../images/githubRelease.png) + */ +@GenerateDocumentation void call(Map parameters = [:]) { handlePipelineStepErrors(stepName: STEP_NAME, stepParameters: parameters) { def script = checkScript(this, parameters) ?: this