-
Notifications
You must be signed in to change notification settings - Fork 1.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #3017 from balopat/move_deprecation_policy
moving deprecation policy to skaffold.dev
- Loading branch information
Showing
5 changed files
with
139 additions
and
113 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters