diff --git a/CHANGELOG.md b/CHANGELOG.md index 4113d53f2f5..680b4d8b4dc 100644 --- a/CHANGELOG.md +++ b/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: diff --git a/deprecation-policy.md b/deprecation-policy.md index a0ceae784df..b3a3e6eb0f2 100644 --- a/deprecation-policy.md +++ b/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. \ No newline at end of file +Deprecation policy has been moved to http://skaffold.dev/docs/references/deprecation diff --git a/docs/content/en/docs/references/deprecation/_index.md b/docs/content/en/docs/references/deprecation/_index.md new file mode 100644 index 00000000000..bb0b64504b4 --- /dev/null +++ b/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. diff --git a/docs/design_proposals/README.md b/docs/design_proposals/README.md index 2b77aeada02..4edb3efb468 100644 --- a/docs/design_proposals/README.md +++ b/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 diff --git a/docs/design_proposals/design-proposal-template.md b/docs/design_proposals/design-proposal-template.md index accbd934f37..25689ab4c91 100644 --- a/docs/design_proposals/design-proposal-template.md +++ b/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