Enhancement: Refine feature deprecation process

[meeech]

People got 'caught out' by a recent feature deprecation in Argo CD

• People weren't really aware it was happening (warnings leading up to this were missed/not visible enough)
• There turned out to be an issue, which prolly would have been caught if more people switched to using the new feature replacing the deprecated feature earlier

Suggestion: Instead of warning/removing feature, add a step where we explicitly disable the feature

Current:

• ...
• 2.7: Warning, this feature will be removed in 2.8
• 2.8: Feature/code removed

Proposed

• ...
• 2.7: Warning, this feature will be removed in 2.8
• 2.8: Feature disabled. Can be re-enabled via a flag
• 2.9: Feature/code removed

This is something all projects would have to deal with, while implementation would be different for each project, the general pattern I think can be agreed on at the argoproj level.

[meeech]

/cc @todaywasawesome

[todaywasawesome]

Ultimately, we're talking about the best way to communicate deprecation.

What if we could flag applications that were using deprecated features? Like maybe it's a sync warning.

[todaywasawesome]

From the contributor's meeting this morning. There was a bit push to start fully adopting semver. Generally major versions are the only ones meant to include breaking changes. I think this is deadon and should be our policy.

However, I think without some additional UI tells that deprecation is happening people will still miss it.

[crenshaw-dev]

I think I'd be willing to sacrifice the UX of those who don't read major release notes for the lower maintenance burden of avoiding a UI-based deprecation warning system.

[hblixt]

I think I'd be willing to sacrifice the UX of those who don't read major release notes for the lower maintenance burden of avoiding a UI-based deprecation warning system.

Agreed. We should be able to assume that people at least read the deprecation warning section of the minor version release notes or the breaking changes section of the major version release notes.

[todaywasawesome]

argoproj/argo-cd#18111

[agilgur5]

I mentioned that Workflows explicitly does not follow SemVer per its docs in argoproj/argo-cd#18111 (review) and today's Maintainers Meeting

With regard to deprecation, Workflows has historically made breaking changes with at least 1 or 2 versions of backward-compat / deprecation window of the old feature. Workflows's Executors are one example of that, see argoproj/argo-workflows#12975 (Emissary was added in 3.1, became default in 3.3, others were removed in 3.4, docs remained until 3.6)

Workflows also does have a UI popup modal whenever the version changes, but popups in general are commonly ignored on the web due to their proliferation (and over-use by ads in particular), so I can't say how effective it is. I know I've missed updates there myself in the past as I just automatically close pop-ups in my browser 😅

What if we could flag applications that were using deprecated features? Like maybe it's a sync warning.

This wouldn't cover all deprecations but that sounds particularly useful to me.

In-line UI and CLI warnings are definitely noticed more. For instance, Workflows has various cost optimization suggestions that pop up in the UI and link to the docs and users have even noticed when they're subtly wrong due to new features (e.g. argoproj/argo-workflows#12395).

argo-helm could also print a warning if a deprecated configuration was used during upgrade/installation.