From a0f9c3669fe062384912e41bd84fa879f190ff1a Mon Sep 17 00:00:00 2001 From: Roland Stengel Date: Mon, 18 Oct 2021 15:16:22 +0200 Subject: [PATCH] isChangeInDevelopment documentation (#3140) * checkChangeInDevelopment to GO - add groovy step isChangeInDevelopment - direct to new Groovy - direct to GO --- cmd/isChangeInDevelopment_generated.go | 8 +- .../docs/steps/checkChangeInDevelopment.md | 29 ++++++- .../docs/steps/isChangeInDevelopment.md | 79 +++++++++++++++++++ .../steps/transportRequestUploadSOLMAN.md | 2 +- documentation/mkdocs.yml | 3 +- resources/metadata/isChangeInDevelopment.yaml | 4 +- 6 files changed, 115 insertions(+), 10 deletions(-) create mode 100644 documentation/docs/steps/isChangeInDevelopment.md diff --git a/cmd/isChangeInDevelopment_generated.go b/cmd/isChangeInDevelopment_generated.go index 82d7b9869..3d3547a6b 100644 --- a/cmd/isChangeInDevelopment_generated.go +++ b/cmd/isChangeInDevelopment_generated.go @@ -54,7 +54,7 @@ func (p *isChangeInDevelopmentCommonPipelineEnvironment) persist(path, resourceN } } -// IsChangeInDevelopmentCommand Checks if a certain change is in status 'in development' +// IsChangeInDevelopmentCommand This step checks if a certain change is in status 'in development' func IsChangeInDevelopmentCommand() *cobra.Command { const STEP_NAME = "isChangeInDevelopment" @@ -66,8 +66,8 @@ func IsChangeInDevelopmentCommand() *cobra.Command { var createIsChangeInDevelopmentCmd = &cobra.Command{ Use: STEP_NAME, - Short: "Checks if a certain change is in status 'in development'", - Long: `"Checks if a certain change is in status 'in development'"`, + Short: "This step checks if a certain change is in status 'in development'", + Long: `This step checks if a certain change is in status 'in development'`, PreRunE: func(cmd *cobra.Command, _ []string) error { startTime = time.Now() log.SetStepName(STEP_NAME) @@ -161,7 +161,7 @@ func isChangeInDevelopmentMetadata() config.StepData { Metadata: config.StepMetadata{ Name: "isChangeInDevelopment", Aliases: []config.Alias{}, - Description: "Checks if a certain change is in status 'in development'", + Description: "This step checks if a certain change is in status 'in development'", }, Spec: config.StepSpec{ Inputs: config.StepInputs{ diff --git a/documentation/docs/steps/checkChangeInDevelopment.md b/documentation/docs/steps/checkChangeInDevelopment.md index b1f770613..8f66bb7bb 100644 --- a/documentation/docs/steps/checkChangeInDevelopment.md +++ b/documentation/docs/steps/checkChangeInDevelopment.md @@ -2,9 +2,34 @@ ## ${docGenDescription} -## Prerequisites +## Migration Guide -* No prerequisites +**Note:** This step has been deprecated. Use the new step [isChangeInDevelopment](isChangeInDevelopment.md) instead. + +Adjust your parameters to the naming convention of the new step. +Adjust the unsupported parameters as indicated in the table below: + +| Unsupported Parameter | New Parameter | +| ------------- | ------------- | +| changeManagement/type | This parameter has been removed. `SOLMAN` is the only backend type supported. | +| changeManagement/``/docker/envVars | `dockerEnvVars` | +| changeManagement/``/docker/image | `dockerImage` | +| changeManagement/``/docker/options | `dockerOptions` | +| changeManagement/``/docker/pullImage | `dockerPullImage` | +| changeManagement/git/format | This parameter has been removed. Make sure that the IDS of your change document and transport request are part of the Git commit message body. | + +Your config.yml file should look as follows: + +```yaml +general: + +# new naming convention +steps: + isChangeInDevelopment: + dockerImage: 'ppiper/cm-client' +``` + +**Note:** The new step does not comprise the retrieval of the change document ID from the Git repository anymore. Use the step [transportRequestDocIDFromGit](transportRequestDocIDFromGit.md) instead. ## ${docGenParameters} diff --git a/documentation/docs/steps/isChangeInDevelopment.md b/documentation/docs/steps/isChangeInDevelopment.md new file mode 100644 index 000000000..24dcf1f61 --- /dev/null +++ b/documentation/docs/steps/isChangeInDevelopment.md @@ -0,0 +1,79 @@ +# ${docGenStepName} + +## ${docGenDescription} + +## Prerequisites + +* You have an SAP Solution Manager user to which you have assigned the roles required for uploading. See [SAP Solution Manager Administration](https://help.sap.com/viewer/c413647f87a54db59d18cb074ce3dafd/7.2.12/en-US/11505ddff03c4d74976dae648743e10e.html). +* You have created a change document. +* You have installed the Change Management Client with the needed certificates. See [Change Management Client](transportRequestUploadSOLMAN.md#Change-Management-Client). + +## Specifying the Change Document + +The target of the status check is a change document identified by an identifier (ID). + +Specify the ID by [step parameter](transportRequestUploadSOLMAN#By-Step-Parameter) or [common pipeline environment](transportRequestUploadSOLMAN#Common-Pipeline-Environment). + +## Return Value + +The step `isChangeInDevelopment` returns a boolean value by setting the custom key +`custom.isChangeInDevelopment` of the common pipeline environment: + +- `true` if the change document is in status `in development`. + +- `false` if the change document is _**not**_ in status `in development`. In this case, `AbortException` terminates the execution of the pipeline job. + +```groovy +// pipeline script + isChangeInDevelopment( script: this ) + ... +``` + +You can omit this exception by setting the configuration parameter `failIfStatusIsNotInDevelopment` to `false`: + +```groovy +// pipeline script + isChangeInDevelopment( script: this, failIfStatusIsNotInDevelopment: false ) + + if(commonPipelineEnvironment.getValue( 'isChangeInDevelopment' ) { + ... + } +``` + +## ${docGenParameters} + +## ${docGenConfiguration} + +## ${docJenkinsPluginDependencies} + +## Examples + +```yaml +# config.yaml +general: + changeManagement: + credentialsId: 'SOLMAN_CRED_ID' + endpoint: 'https://example.org/cm/solman/endpoint' + +steps: + isChangeInDevelopment: + dockerImage: 'ppiper/cm-client' + + transportRequestUploadSOLMAN: + dockerImage: 'ppiper/cm-client' + applicationId: 'APPID', + filePath: '/path/file.ext', +``` + +```groovy +// pipeline script + ... + stage('Upload') { + transportRequestDocIDFromGit( script: this ) + + isChangeInDevelopment( script: this ) + + transportRequestReqIDFromGit( script: this ) + transportRequestUploadSOLMAN( script: this ) + } +``` diff --git a/documentation/docs/steps/transportRequestUploadSOLMAN.md b/documentation/docs/steps/transportRequestUploadSOLMAN.md index e1b6d02ea..7a8a0149e 100644 --- a/documentation/docs/steps/transportRequestUploadSOLMAN.md +++ b/documentation/docs/steps/transportRequestUploadSOLMAN.md @@ -7,7 +7,7 @@ * You have an SAP Solution Manager user account and the roles required for uploading. See [SAP Solution Manager Administration](https://help.sap.com/viewer/c413647f87a54db59d18cb074ce3dafd/7.2.12/en-US/11505ddff03c4d74976dae648743e10e.html). * You have a change document to which your transport request is coupled. * You have a transport request, which is the target container of the upload. -* You have installed the Change Management Client with the needed certificates. See [Change Management Client](#Change Management Client). +* You have installed the Change Management Client with the needed certificates. See [Change Management Client](#Change-Management-Client). ## Change Management Client diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index c71e59ca7..523316323 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -67,7 +67,6 @@ nav: - artifactPrepareVersion: steps/artifactPrepareVersion.md - batsExecuteTests: steps/batsExecuteTests.md - buildExecute: steps/buildExecute.md - - checkChangeInDevelopment: steps/checkChangeInDevelopment.md - checkmarxExecuteScan: steps/checkmarxExecuteScan.md - checksPublishResults: steps/checksPublishResults.md - cfManifestSubstituteVariables: steps/cfManifestSubstituteVariables.md @@ -112,6 +111,7 @@ nav: - integrationArtifactUnDeploy: steps/integrationArtifactUnDeploy.md - integrationArtifactUpdateConfiguration: steps/integrationArtifactUpdateConfiguration.md - integrationArtifactUpload: steps/integrationArtifactUpload.md + - isChangeInDevelopment: steps/isChangeInDevelopment.md - jenkinsMaterializeLog: steps/jenkinsMaterializeLog.md - kanikoExecute: steps/kanikoExecute.md - karmaExecuteTests: steps/karmaExecuteTests.md @@ -161,6 +161,7 @@ nav: - xsDeploy: steps/xsDeploy.md - 'Library Steps (deprecated)': - artifactSetVersion: steps/artifactSetVersion.md + - checkChangeInDevelopment: steps/checkChangeInDevelopment.md - npmExecute: steps/npmExecute.md - transportRequestUploadFile: steps/transportRequestUploadFile.md - 'Command line tool': cli/index.md diff --git a/resources/metadata/isChangeInDevelopment.yaml b/resources/metadata/isChangeInDevelopment.yaml index 3f33259d5..a28156aef 100644 --- a/resources/metadata/isChangeInDevelopment.yaml +++ b/resources/metadata/isChangeInDevelopment.yaml @@ -1,8 +1,8 @@ metadata: name: isChangeInDevelopment - description: "Checks if a certain change is in status 'in development'" + description: This step checks if a certain change is in status 'in development' longDescription: | - "Checks if a certain change is in status 'in development'" + This step checks if a certain change is in status 'in development' spec: inputs: