moving deprecation policy to skaffold.dev

Author: balopat

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 *Note*: This release comes with a new config version `v1beta15`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
         The env vars `DIGEST`, `DIGEST_HEX` and `DIGEST_ALGO` now fail if found in `envTemplate` fields. 
 
 Highlights: 
@@ -82,7 +82,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta14`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.        
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.        
         The env vars `DIGEST`, `DIGEST_HEX` and `DIGEST_ALGO` won't work anymore in envTemplates.
 
 New Features:
@@ -412,7 +412,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta13`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 New Features:
 * File output flag for writing built images to a specified file [#2476](https://github.com/GoogleContainerTools/skaffold/pull/2476)
@@ -495,7 +495,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta12`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 New Features:
 * Add support for user defined port forwarding [#2336](https://github.com/GoogleContainerTools/skaffold/pull/2336)
@@ -705,7 +705,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta11`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 New Features: 
 
@@ -777,7 +777,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta10`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 **Note**: `skaffold deploy` now requires images to be built first, `skaffold deploy` will not build images itself. 
 
@@ -858,7 +858,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta9`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 New Features: 
 * Git tagger variants (Tags, CommitSha, AbbrevCommitSha) [#1902](https://github.com/GoogleContainerTools/skaffold/pull/1902)
@@ -919,7 +919,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta8`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 New Features:
 
@@ -1024,7 +1024,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta7`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 
 *Deprecation notice*: With this release we mark for deprecation the `flags` (KanikoArtifact.AdditionalFlags) field in kaniko; instead Kaniko's additional flags will now be represented as unique fields under `kaniko` per artifact (`KanikoArtifact` type).
@@ -1115,7 +1115,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta6`.
 To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 New Features:
 * Add gRPC based event API [#1574](https://github.com/GoogleContainerTools/skaffold/pull/1574)
@@ -1168,7 +1168,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta5`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 *Deprecation notice*: With this release we mark for deprecation the following env variables in the `envTemplate` tagger:
 - `DIGEST`
@@ -1241,7 +1241,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta4`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 New features:
 * Introduce configuration option to configure image pushing per kube-context [#1355](https://github.com/GoogleContainerTools/skaffold/pull/1355)
@@ -1331,7 +1331,7 @@ Huge thanks goes out to all of our contributors for this release:
 
 *Note*: This release comes with a new config version `v1beta3`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 New Features:
 * Add support for urls in deploy.kubectl.manifests [#1408](https://github.com/GoogleContainerTools/skaffold/pull/1408)
@@ -1405,7 +1405,7 @@ Huge thank you for this release towards our contributors:
 
 *Note*: This release comes with a new config version `v1beta2`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 New Features:
 
@@ -1465,7 +1465,7 @@ Huge thank you for this release towards our contributors:
 
 *Note*: This release comes with a new config version `v1beta1`.
         To upgrade your `skaffold.yaml`, use `skaffold fix`. If you don't upgrade, skaffold will auto-upgrade in memory as best it can, and print a warning message.
-        See [deprecation-policy.md](/deprecation-policy.md) for details on what beta means.
+        See [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/) for details on what beta means.
 
 
 New features:

deprecation-policy.md

@@ -1,97 +1,3 @@
-# Skaffold deprecation policy
+# Moved 
 
-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 the following places if applicable
-    1. [Document](./docs) changes in relevant sections. These docs will be
-        published to [offical skaffold website](https://skaffold.dev/docs/)
-    2. Release notes
-    3. Command help
-    4. Log messages
-    5. https://skaffold.dev/docs/references/yaml/
-    6. [deprecation policy](/deprecation-policy.md)
-
-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
-  - plugins gcb: alpha
-- Artifact types:
-  - Dockerfile: beta
-  - Bazel: beta
-  - Jib: beta
-- 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
-- Debug: alpha
-
-## Skaffold commands
-
-Commands and their flags are subject to the deprecation policy based on the following table list:
-
-- build:  beta
-- completion:  beta
-- config:  alpha
-- debug: alpha
-- delete:  beta
-- deploy:  beta
-- dev:  beta
-- diagnose:  beta
-- fix:  beta
-- help:  beta
-- init:  alpha
-- run:  beta
-- version:  beta
-
-
-## Current deprecation notices
-
-
-03/15/2019: With release v0.25.0 we mark for deprecation the `flags` field in kaniko (`KanikoArtifact.AdditionalFlags`) , instead Kaniko's additional flags will now be represented as unique fields under `kaniko` per artifact (`KanikoArtifact` type).
-This flag will will be removed earliest 06/15/2019.
+Deprecation policy has been moved to http://skaffold.dev/docs/references/deprecation

docs/content/en/docs/references/deprecation/_index.md

@@ -0,0 +1,120 @@
+---
+title: "Deprecation policy"
+linkTitle: "Deprecation policy"
+weight: 300
+---
+
+# Skaffold deprecation policy
+
+This document sets out the deprecation policy for Skaffold, and outlines how the Skaffold project will approach the introduction of breaking changes over time.
+
+Deprecation policy applies only to Stable Builds. Bleeding Edge builds may have less stable implementations.  
+
+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 the following places if applicable
+    1. deprecation policy - this document 
+    1. [Document on this site]({{< relref "/docs" >}}) changes in relevant sections
+    1. [Release notes](https://github.com/GoogleContainerTools/skaffold/blob/master/CHANGELOG.md)
+    1. [Command help]({{< relref "/docs/references/cli" >}})
+    1. Log messages
+    1. [skaffold yaml reference]({{< relref "/docs/references/yaml" >}})
+    
+
+2. if applicable, [inspired by 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 and its features are considered Beta unless specified (in this document, CLI reference, config YAML reference or in docs in skaffold.dev).  
+Skaffold is constantly evolving with the tools space, we want to be able to experiment and sometimes change things. 
+In order to be transparent about the maturity of feature areas and things that might change we offer the feature level maturity matrix that we keep up to date.
+
+## 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 features
+
+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
+  - plugins gcb: alpha
+- Artifact types:
+  - Dockerfile: beta
+  - Bazel: beta
+  - Jib: beta
+- 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
+- Debug: alpha
+
+## Skaffold commands
+
+Commands and their flags are subject to the deprecation policy based on the following table list:
+
+- build:  beta
+- completion:  beta
+- config:  alpha
+- debug: alpha
+- delete:  beta
+- deploy:  beta
+- dev:  beta
+- diagnose:  beta
+- fix:  beta
+- help:  beta
+- init:  alpha
+- run:  beta
+- version:  beta
+
+
+## Exceptions 
+
+No policy can cover every possible situation. 
+This policy is a living document, and will evolve over time. 
+In practice, there will be situations that do not fit neatly into this policy, or for which this policy becomes a serious impediment. 
+Examples could be getting fixes fast for a serious vulnerability, a destructive bug or requirements that might be imposed by third parties (such as legal requirements).
+Such situations should be discussed on the given bugs / feature requests and during Skaffold Office Hours, always bearing in mind that Skaffold is committed to being a stable system that, as much as possible, never breaks users. 
+Exceptions will always be announced in all relevant release notes.
+
+## Current deprecation notices
+
+
+03/15/2019: With release v0.25.0 we mark for deprecation the `flags` field in kaniko (`KanikoArtifact.AdditionalFlags`) , instead Kaniko's additional flags will now be represented as unique fields under `kaniko` per artifact (`KanikoArtifact` type).
+This flag will will be removed earliest 06/15/2019.

docs/design_proposals/README.md

@@ -28,7 +28,7 @@ sure:
    philosophy for the tool and not a one off solution for a specific use case.
 2. The feature/change scope is well defined.
 3. When changing any existing feature, the implementation plan adheres to
-   [skaffold deprecation policy](./../../deprecation-policy.md).
+   [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/).
 
 Once the proposal has been approved, we can move discussions to our bi-weekly
 meetings to address any open concerns,and to reach a final decision on whether

docs/design_proposals/design-proposal-template.md

@@ -62,7 +62,7 @@ Please describe your solution. Please list any:
 For a new config change, please mention:
 
 * Is it backwards compatible? If not, what is the deprecation policy?
-  Refer to the [deprecation policy requirements.](./../../deprecation-policy.md#how-do-we-deprecate-things)
+  Refer to the [Skaffold Deprecation Policy](http://skaffold.dev/docs/references/deprecation/).
   for details.
 
 ### Open Issues/Questions