-
Notifications
You must be signed in to change notification settings - Fork 5.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve documentation on experimetal (alpha/beta) features #20336
Open
Labels
Comments
crenshaw-dev
added a commit
to crenshaw-dev/argo-cd
that referenced
this issue
Oct 10, 2024
Signed-off-by: Michael Crenshaw <[email protected]>
blakepettersson
pushed a commit
that referenced
this issue
Oct 14, 2024
) * docs: feature maturity page for alpha and beta features (#20336) Signed-off-by: Michael Crenshaw <[email protected]> * typos Signed-off-by: Michael Crenshaw <[email protected]> --------- Signed-off-by: Michael Crenshaw <[email protected]>
Reopening as the PR merged above, while clarifying the list of alpha/beta features, does not help identify the actual configurations affected by the features. I will experiment on an additional PR Maybe something like
|
austin5219
pushed a commit
to austin5219/argo-cd
that referenced
this issue
Oct 16, 2024
…) (argoproj#20337) * docs: feature maturity page for alpha and beta features (argoproj#20336) Signed-off-by: Michael Crenshaw <[email protected]> * typos Signed-off-by: Michael Crenshaw <[email protected]> --------- Signed-off-by: Michael Crenshaw <[email protected]> Signed-off-by: austin5219 <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Labels
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:
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:
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.
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:
The text was updated successfully, but these errors were encountered: