Skip to content

Commit 08f80ce

Browse files
add guidelines for adding new features to stable APIs (#3182)
Signed-off-by: Whitney Griffith <whitney.griffith16@gmail.com>
1 parent e4a1b46 commit 08f80ce

File tree

1 file changed

+8
-0
lines changed

1 file changed

+8
-0
lines changed

GUIDELINES.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,14 @@ major versions and releases, such as `v1alpha`, `v2beta`, or
246246
a lack of a conversion webhook, the schema of all versions of an API
247247
must be strictly identical.
248248

249+
New APIs progress through feature stages according to our [policy](https://istio.io/latest/docs/releases/feature-stages/) before achieving stability, `v1`. When adding a new API, follow these steps:
250+
- Add `// +cue-gen:<Replace with API Name>:releaseChannel:extended` tag to the proto message definition of the API.
251+
- Update the stable validation policy to exclude the new API in the [base chart](https://github.com/istio/istio/blob/199f76a601fc4520b675169d4b53503edfaa34e3/manifests/charts/base/templates/validatingadmissionpolicy.yaml#L31) and [istio-discovery chart](https://github.com/istio/istio/blob/199f76a601fc4520b675169d4b53503edfaa34e3/manifests/charts/istio-control/istio-discovery/templates/validatingadmissionpolicy.yaml#L37) manifests.
252+
253+
Similarly, new API fields added to a stable `v1` API independently progress through feature stages based on our [policy](https://istio.io/latest/docs/releases/feature-stages/) before achieving stability. When adding a new API field to a stable `v1` API, follow these steps:
254+
- Add `// +cue-gen:<Replace with API Name>:releaseChannel:extended` tag to the proto field definition.
255+
- Update the stable validation policy to exclude the new field in the [base chart](https://github.com/istio/istio/blob/199f76a601fc4520b675169d4b53503edfaa34e3/manifests/charts/base/templates/validatingadmissionpolicy.yaml#L31) and [istio-discovery chart](https://github.com/istio/istio/blob/199f76a601fc4520b675169d4b53503edfaa34e3/manifests/charts/istio-control/istio-discovery/templates/validatingadmissionpolicy.yaml#L37) manifests.
256+
249257
Deprecating a feature in an API release is allowed by following
250258
the applicable deprecation process. The reason to allow
251259
deprecation of individual features in a release is that it is

0 commit comments

Comments
 (0)