search

solo-io / gloo

The Feature-rich, Kubernetes-native, Next-Generation API Gateway Built on Envoy
https://docs.solo.io/
Apache License 2.0
4.07k stars 437 forks source link

Deprecation Strategy #7278

Open jbohanon opened 1 year ago

jbohanon commented 1 year ago

Version

No response

Is your feature request related to a problem? Please describe.

We currently do not have a concrete strategy for deprecating API fields or messages.

Describe the solution you'd like

Some strategy for deprecating APIs and subsequently removing code/reserving fields. This may look like a simple policy for denoting the version in which that deprecation occurred and taking the appropriate removal actions when that version falls out of LTS.

Describe alternatives you've considered

No response

Additional Context

No response

inFocus7 commented 1 year ago

Would good to have a separate changelog entry type for DEPRECATED or maybe OBSOLETE/REMOVED APIs. For obsolete fields, it'd technically still be a BREAKING_CHANGE as well, but would be good to have its own quick-to-parse section in our change-log for users.

Kubernetes has some neat policies we can get ideas from. Their setup is a bit kubebuilder-esque with vX{alpha/beta}Y versioning, but still some great ideas in there we can generalize.

Not sure if we do this already, but if we use kubebuilder to generate manifests, then we can maybe leverage the // +kubebuilder:deprecatedversion:warning= marker to warn users. I see we use [deprecated=true] in our protos, which likely already does what I crossed out.

nfuden commented 1 year ago

Our protos mainly come from Envoy so if we are to use a strategy for deprecation we likely would want it more closely aligned with their strategy than kubernetes.