Merge pull request #419 from marcusholl/pr/piper-api

Pr/piper api

README.md

@@ -49,9 +49,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 not part of the API and are subjected to change
-without prior notice.
+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
+methods/types needs to be announced, discussed and agreed.
 
 # Requirements
 

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'

src/com/sap/piper/API.groovy

@@ -0,0 +1,23 @@
+package com.sap.piper
+
+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
+ * 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 corresponding class/method to adapt to the change accordingly.
+ */
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target([ElementType.METHOD, ElementType.TYPE])
+@interface API {
+    /**
+     * API marked as deprecated should not be used and moved to non-deprecated API.
+     */
+    boolean deprecated() default false
+}

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 = [:]) {

src/com/sap/piper/ConfigurationLoader.groovy

@@ -2,6 +2,7 @@ package com.sap.piper
 
 import com.cloudbees.groovy.cps.NonCPS
 
+@API(deprecated = true)
 class ConfigurationLoader implements Serializable {
     @NonCPS
     static Map stepConfiguration(script, String stepName) {

src/com/sap/piper/ConfigurationMerger.groovy

@@ -2,6 +2,7 @@ package com.sap.piper
 
 import com.cloudbees.groovy.cps.NonCPS
 
+@API(deprecated = true)
 class ConfigurationMerger {
     @NonCPS
     static Map merge(Map configs, Set configKeys, Map defaults) {

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
 

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 }

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