adding deprecation policy and document component stability (#1324)

deprecation-policy.md

@@ -0,0 +1,85 @@
+# Skaffold deprecation policy
+
+Skaffold adopts the [Kubernetes deprecation policy for admin facing components](https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecating-a-flag-or-cli). In summary, deprecations to a flag or CLI command require the following notification periods, depending on the release track:
+
+| Release Track | Deprecation Period | 
+| -------- | -------- | 
+| Alpha (experimental)    |0 releases     |
+| Beta (pre-release) | 3 months or 1 release (whichever is longer)| 
+| GA (generally available)   | 6 months or 1 release (whichever is longer) | 
+
+**Breaking changes** 
+A breaking change is when the primary functionality of a feature changes in a way that the user has to make changes to their workflows/configuration.
+- **Breaking config change**:  In case of skaffold's pipeline config (skaffold.yaml) a breaking change between an old and new version occurs when the skaffold binary cannot parse the input yaml with auto-upgrade. This can happen when the new version removes a feature or when the new version introduces a mandatory field with no default value
+- **Breaking functional change**: functional changes that force user workflow changes even when the config is the same or upgradeable.
+
+## How do we deprecate things? 
+
+A "deprecation event" would coincide with a release. 
+
+1. we document the deprecation in 
+a.) docs
+b.) release notes 
+c.) command help (if applicable)
+d.) annotated-skaffold.yaml (if applicable)
+
+2. if applicable, [from the kubernetes policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecating-a-flag-or-cli): 
+ > Rule #6: Deprecated CLI elements must emit warnings (optionally disable) when used.
+
+# Current maturity of skaffold 
+
+## Skaffold.yaml (pipeline config)
+
+The pipeline config, i.e. `skaffold.yaml` is **beta**. 
+
+This means that you can safely depend on the skaffold config with the assumption that skaffold will auto-upgrade to the latest version:
+
+- Removal and non-upgradable changes are subject to the deprecation policy for all (even new) features under the config. 
+- Auto-upgradable changes are not considered breaking changes. 
+
+## Skaffold components
+
+We are committed to design for auto-upgradeable changes in the config. 
+However the **behavior** of individual component might suffer breaking changes depending on maturity.
+
+- Filewatcher: beta
+- Builders
+  - local (beta) 
+  - googleCloudBuild (beta) 
+  - kaniko (beta) 
+- Artifact types: 
+  - Dockerfile: beta
+  - Bazel: beta
+  - jibMaven: alpha
+  - jibGradle: alpha 
+- Filesync: alpha
+- Port-forwarding: alpha 
+- Taggers: beta 
+  - gitCommit : beta
+  - Sha256: beta
+  - dateTime : beta
+  - envTagger: beta
+- Testers: alpha
+  - Structure tests: alpha
+- Deployers: beta
+    - Helm: beta 
+    - Kustomize: beta
+    - Kubectl: beta 
+- Profiles: beta
+
+## Skaffold commands 
+
+Commands and their flags are subject to the deprecation policy based on the following table list:
+
+- build:  beta 
+- completion:  beta 
+- config:  alpha 
+- delete:  beta 
+- deploy:  beta 
+- dev:  beta 
+- diagnose:  beta 
+- fix:  beta 
+- help:  beta 
+- init:  alpha 
+- run:  beta 
+- version:  beta 

integration/examples/annotated-skaffold.yaml

@@ -1,18 +1,18 @@
 apiVersion: skaffold/v1beta1
 kind: Config
 build:
-  # tagPolicy determines how Skaffold is going to tag your images.
+  # tagPolicy (beta) determines how Skaffold is going to tag your images.
   # We provide a few strategies here, although you most likely won't need to care!
-  # The policy can `gitCommit`, `sha256`, `envTemplate` or `dateTime`.
+  # The policy can `gitCommit` (beta), `sha256` (beta), `envTemplate` (beta) or `dateTime` (beta).
   # If not specified, it defaults to `gitCommit: {}`.
   tagPolicy:
-    # Tag the image with the git commit of your current repository.
+    # gitCommit tags the image with the git commit of your current repository.
     gitCommit: {}
 
-    # Tag the image with the checksum of the built image (image id).
+    # sha256 tags the image with the checksum of the built image (image id).
     # sha256: {}
 
-    # Tag the image with a configurable template string.
+    # envTemplate tags the image with a configurable template string.
     # The template must be in the golang text/template syntax: https://golang.org/pkg/text/template/
     # The template is compiled and executed against the current environment,
     # with those variables injected:
@@ -24,7 +24,7 @@ build:
     # envTemplate:
     #  template: "{{.RELEASE}}-{{.IMAGE_NAME}}"
 
-    # Tag the image with the build timestamp.
+    # dateTime tags the image with the build timestamp.
     #  The format can be overridden with golang formats, see: https://golang.org/pkg/time/#Time.Format
     #    Default format is "2006-01-02_15-04-05.999_MST
     #  The timezone is by default the local timezone, this can be overridden, see https://golang.org/pkg/time/#Time.LoadLocation
@@ -39,13 +39,13 @@ build:
   - image: gcr.io/k8s-skaffold/skaffold-example
     # The path to your dockerfile context. Defaults to ".".
     context: ../examples/getting-started
-    # Skaffold can sync local files with remote pods instead
+    # Skaffold can sync local files with remote pods (alpha) instead
     # of rebuilding the whole artifact's image. This is a mapping
     # of local files to sync to remote folders.
     # sync:
     #   '*.py': .
 
-    # Each artifact is of a given type among: `docker`, `bazel`, `jibMaven` and `jibGradle`.
+    # Each artifact is of a given type among: `docker` (beta), `bazel` (beta), `jibMaven` (alpha) and `jibGradle` (alpha).
     # If not specified, it defaults to `docker: {}`.
     docker:
       # Dockerfile's location relative to workspace. Defaults to "Dockerfile"
@@ -80,7 +80,7 @@ build:
     #  project: projectname   # selects which gradle project to build
 
 # This next section is where you'll put your specific builder configuration.
-  # Valid builders are `local`, `googleCloudBuild` and `kaniko`.
+  # Valid builders are `local` (beta), `googleCloudBuild` (beta) and `kaniko` (beta).
   # Defaults to `local: {}`
 
   # Pushing the images can be skipped. If no value is specified, it'll default to
@@ -139,7 +139,7 @@ build:
 # The deploy section has all the information needed to deploy. Along with build:
 # it is a required section.
 deploy:
-  # The type of the deployment method can be `kubectl`, `helm` or `kustomize`.
+  # The type of the deployment method can be `kubectl` (beta), `helm` (beta) or `kustomize` (beta).
 
   # The kubectl deployer uses  a client side `kubectl apply` to apply the manifests to the cluster.
   # You'll need a kubectl CLI version installed that's compatible with your cluster.
@@ -199,7 +199,7 @@ deploy:
     #     # Note that you can specify both static string or dynamic template.
     #     appVersion: {{ .CHART_VERSION }}-dirty
 
-# profiles section has all the profile information which can be used to override any build or deploy configuration
+# profiles (beta) section has all the profile information which can be used to override any build or deploy configuration
 profiles:
   - name: gcb
     build: