From 7f1713148f44fe9b6d1b8832e001375ae8d632bb Mon Sep 17 00:00:00 2001 From: Florian Wilhelm Date: Tue, 8 Jan 2019 17:35:53 +0100 Subject: [PATCH 1/6] Extend api --- README.md | 10 +++++----- src/com/sap/piper/ConfigurationHelper.groovy | 6 +----- src/com/sap/piper/ConfigurationLoader.groovy | 1 + src/com/sap/piper/ConfigurationMerger.groovy | 1 + src/com/sap/piper/DefaultValueCache.groovy | 1 + src/com/sap/piper/JenkinsUtils.groovy | 1 + src/com/sap/piper/k8s/ContainerMap.groovy | 3 +++ 7 files changed, 13 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index be0a46abe..41e20e80f 100644 --- a/README.md +++ b/README.md @@ -50,11 +50,11 @@ provided pipeline library. ## API -All steps are intended to be used by Pipelines. All the classes / groovy-scripts -contained in the `src` folder are by default not part of the API and are subjected to change -without prior notice. Types and methods annotated with `@API` are considered to be API, used e.g. -from other shared libraries. Changes to those methods/types needs to be announced, disussed and -agreed. +All steps (`vars` directory) are intended to be used by Pipelines and are considered API. +All the classes / groovy-scripts contained in the `src` folder are by default not part of +the API and are subjected to change without prior notice. Types and methods annotated with +`@API` are considered to be API, used e.g. from other shared libraries. Changes to those +methods/types needs to be announced, discussed and agreed. # Requirements diff --git a/src/com/sap/piper/ConfigurationHelper.groovy b/src/com/sap/piper/ConfigurationHelper.groovy index 116fa8051..d8781eafd 100644 --- a/src/com/sap/piper/ConfigurationHelper.groovy +++ b/src/com/sap/piper/ConfigurationHelper.groovy @@ -2,6 +2,7 @@ package com.sap.piper import com.cloudbees.groovy.cps.NonCPS +@API class ConfigurationHelper implements Serializable { static ConfigurationHelper newInstance(Script step, Map config = [:]) { @@ -31,19 +32,16 @@ class ConfigurationHelper implements Serializable { return this } - @API ConfigurationHelper mixinGeneralConfig(commonPipelineEnvironment, Set filter = null, Map compatibleParameters = [:]){ Map stepConfiguration = ConfigurationLoader.generalConfiguration([commonPipelineEnvironment: commonPipelineEnvironment]) return mixin(stepConfiguration, filter, compatibleParameters) } - @API ConfigurationHelper mixinStageConfig(commonPipelineEnvironment, stageName, Set filter = null, Map compatibleParameters = [:]){ Map stageConfiguration = ConfigurationLoader.stageConfiguration([commonPipelineEnvironment: commonPipelineEnvironment], stageName) return mixin(stageConfiguration, filter, compatibleParameters) } - @API ConfigurationHelper mixinStepConfig(commonPipelineEnvironment, Set filter = null, Map compatibleParameters = [:]){ Map stepConfiguration = ConfigurationLoader.stepConfiguration([commonPipelineEnvironment: commonPipelineEnvironment], name) return mixin(stepConfiguration, filter, compatibleParameters) @@ -103,7 +101,6 @@ class ConfigurationHelper implements Serializable { return this } - @API @NonCPS // required because we have a closure in the // method body that cannot be CPS transformed Map use(){ @@ -152,7 +149,6 @@ class ConfigurationHelper implements Serializable { } } - @API ConfigurationHelper withMandatoryProperty(key, errorMessage = null, condition = null){ if(condition){ if(condition(this.config)) diff --git a/src/com/sap/piper/ConfigurationLoader.groovy b/src/com/sap/piper/ConfigurationLoader.groovy index f3c8a15a2..c140cfd35 100644 --- a/src/com/sap/piper/ConfigurationLoader.groovy +++ b/src/com/sap/piper/ConfigurationLoader.groovy @@ -2,6 +2,7 @@ package com.sap.piper import com.cloudbees.groovy.cps.NonCPS +@API class ConfigurationLoader implements Serializable { @NonCPS static Map stepConfiguration(script, String stepName) { diff --git a/src/com/sap/piper/ConfigurationMerger.groovy b/src/com/sap/piper/ConfigurationMerger.groovy index 4c3ec4675..d6988037f 100644 --- a/src/com/sap/piper/ConfigurationMerger.groovy +++ b/src/com/sap/piper/ConfigurationMerger.groovy @@ -2,6 +2,7 @@ package com.sap.piper import com.cloudbees.groovy.cps.NonCPS +@API class ConfigurationMerger { @NonCPS static Map merge(Map configs, Set configKeys, Map defaults) { diff --git a/src/com/sap/piper/DefaultValueCache.groovy b/src/com/sap/piper/DefaultValueCache.groovy index a620d3dce..7ae3ffd1e 100644 --- a/src/com/sap/piper/DefaultValueCache.groovy +++ b/src/com/sap/piper/DefaultValueCache.groovy @@ -2,6 +2,7 @@ package com.sap.piper import com.cloudbees.groovy.cps.NonCPS +@API class DefaultValueCache implements Serializable { private static DefaultValueCache instance diff --git a/src/com/sap/piper/JenkinsUtils.groovy b/src/com/sap/piper/JenkinsUtils.groovy index e8c43005b..f49d158ff 100644 --- a/src/com/sap/piper/JenkinsUtils.groovy +++ b/src/com/sap/piper/JenkinsUtils.groovy @@ -4,6 +4,7 @@ import com.cloudbees.groovy.cps.NonCPS import jenkins.model.Jenkins import org.jenkinsci.plugins.workflow.steps.MissingContextVariableException +@API @NonCPS static def isPluginActive(pluginId) { return Jenkins.instance.pluginManager.plugins.find { p -> p.isActive() && p.getShortName() == pluginId } diff --git a/src/com/sap/piper/k8s/ContainerMap.groovy b/src/com/sap/piper/k8s/ContainerMap.groovy index 5cdaae796..7a9402f57 100644 --- a/src/com/sap/piper/k8s/ContainerMap.groovy +++ b/src/com/sap/piper/k8s/ContainerMap.groovy @@ -1,5 +1,8 @@ package com.sap.piper.k8s +import com.sap.piper.API + +@API @Singleton class ContainerMap { private Map containerMap = null From 33238403d271c74c940afa3888d6feca1dfa072e Mon Sep 17 00:00:00 2001 From: Florian Wilhelm Date: Wed, 23 Jan 2019 09:48:21 +0100 Subject: [PATCH 2/6] Mark old classes as deprecated api --- src/com/sap/piper/API.java | 3 ++- src/com/sap/piper/ConfigurationLoader.groovy | 2 +- src/com/sap/piper/ConfigurationMerger.groovy | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/src/com/sap/piper/API.java b/src/com/sap/piper/API.java index 92bbe7dc6..db5edf40f 100644 --- a/src/com/sap/piper/API.java +++ b/src/com/sap/piper/API.java @@ -10,10 +10,11 @@ import java.lang.annotation.Target; * this shared, e.g. in other shared libraries. In case there is the * need for changing this methods this should be clearly announced * in order to get a consensus about the change and in order to allow - * users of the correponding class/method to adapt to the change accordingly. + * users of the corresponding class/method to adapt to the change accordingly. */ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.METHOD, ElementType.TYPE}) public @interface API { + boolean deprecated() default false; } diff --git a/src/com/sap/piper/ConfigurationLoader.groovy b/src/com/sap/piper/ConfigurationLoader.groovy index c140cfd35..39f2a95a6 100644 --- a/src/com/sap/piper/ConfigurationLoader.groovy +++ b/src/com/sap/piper/ConfigurationLoader.groovy @@ -2,7 +2,7 @@ package com.sap.piper import com.cloudbees.groovy.cps.NonCPS -@API +@API(deprecated = true) class ConfigurationLoader implements Serializable { @NonCPS static Map stepConfiguration(script, String stepName) { diff --git a/src/com/sap/piper/ConfigurationMerger.groovy b/src/com/sap/piper/ConfigurationMerger.groovy index d6988037f..20c58cc14 100644 --- a/src/com/sap/piper/ConfigurationMerger.groovy +++ b/src/com/sap/piper/ConfigurationMerger.groovy @@ -2,7 +2,7 @@ package com.sap.piper import com.cloudbees.groovy.cps.NonCPS -@API +@API(deprecated = true) class ConfigurationMerger { @NonCPS static Map merge(Map configs, Set configKeys, Map defaults) { From a1f8ef10862e3f6a6fb4532aab1dd4b188a2106d Mon Sep 17 00:00:00 2001 From: Florian Wilhelm Date: Wed, 23 Jan 2019 10:07:55 +0100 Subject: [PATCH 3/6] Convert annotation to groovy --- src/com/sap/piper/{API.java => API.groovy} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename src/com/sap/piper/{API.java => API.groovy} (89%) diff --git a/src/com/sap/piper/API.java b/src/com/sap/piper/API.groovy similarity index 89% rename from src/com/sap/piper/API.java rename to src/com/sap/piper/API.groovy index db5edf40f..ee9b11089 100644 --- a/src/com/sap/piper/API.java +++ b/src/com/sap/piper/API.groovy @@ -14,7 +14,7 @@ import java.lang.annotation.Target; */ @Retention(RetentionPolicy.RUNTIME) -@Target({ElementType.METHOD, ElementType.TYPE}) -public @interface API { +@Target([ElementType.METHOD, ElementType.TYPE]) +@interface API { boolean deprecated() default false; } From d4bb237486b800372d8f378c7a49958c037fb33c Mon Sep 17 00:00:00 2001 From: Florian Wilhelm Date: Wed, 23 Jan 2019 10:16:11 +0100 Subject: [PATCH 4/6] Improve --- src/com/sap/piper/API.groovy | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/com/sap/piper/API.groovy b/src/com/sap/piper/API.groovy index ee9b11089..6721d6e8f 100644 --- a/src/com/sap/piper/API.groovy +++ b/src/com/sap/piper/API.groovy @@ -1,9 +1,9 @@ -package com.sap.piper; +package com.sap.piper -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; +import java.lang.annotation.ElementType +import java.lang.annotation.Retention +import java.lang.annotation.RetentionPolicy +import java.lang.annotation.Target /** * Methods or classes annotated with this annotation are used outside @@ -16,5 +16,8 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) @Target([ElementType.METHOD, ElementType.TYPE]) @interface API { - boolean deprecated() default false; + /** + * API marked as deprecated should not be used and moved to non-deprecated API. + */ + boolean deprecated() default false } From 8862fb7186a85fa0a24b68337f93332a01770d52 Mon Sep 17 00:00:00 2001 From: Florian Wilhelm Date: Wed, 23 Jan 2019 11:23:03 +0100 Subject: [PATCH 5/6] Decare resources directory API --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 41e20e80f..876d9bc3c 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ provided pipeline library. ## API -All steps (`vars` directory) are intended to be used by Pipelines and are considered API. +All steps (`vars` and `resources` directory) are intended to be used by Pipelines and are considered API. All the classes / groovy-scripts contained in the `src` folder are by default not part of the API and are subjected to change without prior notice. Types and methods annotated with `@API` are considered to be API, used e.g. from other shared libraries. Changes to those From bb3763bf32f5b2f77fb52e44a7a78d03ff79283e Mon Sep 17 00:00:00 2001 From: Florian Wilhelm Date: Wed, 23 Jan 2019 11:35:18 +0100 Subject: [PATCH 6/6] Hint about api in defaut environment --- resources/default_pipeline_environment.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/resources/default_pipeline_environment.yml b/resources/default_pipeline_environment.yml index fe7ee797f..8cd70b04c 100644 --- a/resources/default_pipeline_environment.yml +++ b/resources/default_pipeline_environment.yml @@ -1,3 +1,8 @@ +# +# ATTENTION: This file is part of the API, breaking changes here directly affect the consumers of the library. +# Please avoid breaking changes if possible. +# + #Project Setup general: productiveBranch: 'master'