Summary

When a new feature is added as an alpha or beta, it often requires changes to the ArgoCD CRD, either in the spec, the status or both. Apart from the documentation on the specific feature and admonition warnings, it is quite hard for a user to distinguish what is GA/Stable from what is not.

This tends to create the false belief that anything in the spec will not be removed or have breaking changes, which is not true based on https://github.com/argoproj/argoproj/blob/b1f9b68795fe75faa3ef38f31696fad6c6b3ebf7/community/feature-status.md.

Motivation

The goal is never to purposely break the user workflows by introducing breaking changes or removing features. However, we rarely get it right the first time!

Sometime using annotations can be a good alternative to avoid modifying the spec. However, it has at least 3 major downside:

1. Needs to be re-implement to spec/status to progress to beta or stable, which affect user experience.
2. Some existing annotations are already considered stable.

I think modifying the spec/status is necessary to implement new features and perform experimentation as first class citizens.

Proposal

To reduce the possible user confusion while maintaining a good user experience for adopters of alpha and beta features, I think we should do the following:

1. Clarify the documentation
   a. Create a new documentation page with all the current alpha and beta features, as well as the explicit list of fields in the spec affected.
   b. Duplicate the information feature status information from argoproj/argoproj in argo-cd docs because most people will not read that documentation.
2. Add CRD documentation on the fields that are alpha/beta. If possible, it would be nice to have these fields lint warnings in IDEs when they are used.

With better documentation, we will increase user awareness when they decide to adopt features that are under development

Alternative (long-term)

I think we should start considering using the Kubernetes apiVersion, which is currently v1alpha1, to allow us to perform these changes in a more Kubernetes way. I don't have much experience on this, but definitely think we should start implementing a versioning strategy + mutation webhook to manage the apiVersions.

Some examples:

• https://gateway-api.sigs.k8s.io/concepts/versioning/#release-channels-eg-experimental-standard (thanks @zachaller)
• https://book.kubebuilder.io/multiversion-tutorial/api-changes