github.com/projectcontour/contour@v1.28.2/site/content/resources/deprecation-policy.md (about)

     1  ---
     2  title: Contour Deprecation Policy
     3  layout: page
     4  ---
     5  
     6  Contour publishes a few APIs, the most notable being the `projectcontour.io` api group of Kubernetes objects and their associated helper code, the command line for `contour`, and the Contour configuration file.
     7  Each of these have deprecation policies, with all of them being based on the [Kubernetes API deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/).
     8  
     9  
    10  
    11  ## `projectcontour.io` API groups (aka Contour CRDs)
    12  
    13  Our Kubernetes CRDs use the Kubernetes API deprecation conventions, including a similar deprecation timeline.
    14  
    15  - There are three levels of stability, Alpha, Beta and GA (in increasing order).
    16  - We may skip the Beta level when we are reasonably confident the schema is good.
    17  
    18  We use similar rules as Kubernetes:
    19  - For Beta and GA versions, API elements may only be removed by incrementing the version of the API group.
    20  - For Alpha versions, rules on behavior changes and API field removal are more lenient, a version bump will not always be required.
    21  - An API version in a given track may not be deprecated until a new API version at least as stable is released.
    22  
    23  
    24  | Sample Version Tag | State | Deprecation timeframe | Notes                                                                                                      |
    25  | ------------------ | ----- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
    26  | v1alpha1           | Alpha | Any time              | Behavior can change any time, Fields can be removed at any time                                            |
    27  | v1beta1            | Beta  | 1 release             | Behavior can change any time, fields won't be removed without a version bump (ie `v1beta1` to `v1beta2`) |
    28  | v1                 | GA    | 1 year                | No fields will be removed, no behavior will substantially change. Fields can be added.                     |
    29  
    30  
    31  ## `projectcontour.io` CRD helper code
    32  
    33  The `projectcontour.io` CRDs contain some helper code, for accessing various parts of the Go structs inside.
    34  
    35  The API guarantees apply here as well, in the following way:
    36  
    37  | Sample Version Tag | State | Change/Deprecation timeframe | Notes                                                                                                      |
    38  | ------------------ | ----- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
    39  | v1alpha1           | Alpha | Any time              | Function and method signatures can change any time. Implementation may change any time.                         |
    40  | v1beta1            | Beta  | 1 release            | Function and method signatures won't change without a version bump. Implementation may change any time. |
    41  | v1                 | GA    | 1 year                | Function and method signatures won't change without a version bump. Implementation may change any time, but behavior changes must be restricted to minor ones (that is, you can change how a return value is made, but not what it means)|
    42  
    43  
    44  
    45  ## Contour command line arguments
    46  
    47  Because removing command line arguments is a breaking operation (that is, the program won't start without them), Contour is committed to a gradual transition for changes here.
    48  
    49  We try to use the following cycle for arguments:
    50  - Argument is announced deprecated, with a timeline for removal. This timeframe must never be shorter than 3 releases, but may be longer if required.
    51  - At the same time, Argument has a warning added, saying that it's deprecated.
    52  - We wait the timeline period
    53  - The argument is removed.
    54  
    55  
    56  
    57  ## Configuration file settings
    58  
    59  We use the following cycle for config file settings:
    60  - Setting is announced deprecated, with a plan for how the functionality will be moved or removed, and a timeline.
    61  - Warning log added for deprecated setting.
    62  - We wait the timeline period
    63  - The setting is moved or removed.
    64