document the upgrade version flow for self-managed

[conceptualshark]

Description

Clarify the recommended upgrade path for Camunda Helm charts, and clean up the Helm page introduction to match this information.

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support.
• This is already available but undocumented and should be released within a week.
• This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
• This is part of a scheduled alpha or minor. (apply alpha or minor label)
• There is no urgency with this change and can be released at any time.

PR Checklist

• My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
• My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

[akeller]

I'd like to see a review from the Distribution team, specifically for this note. Specifically because in the update instructions we mention the following:

When updating from one minor version to the next, you do not need to update to each patch version along the way. However, do not skip minor versions when updating.

Should we also mention (again), in this PR, that you should not skip minor versions? Or do we think this is clear enough as is?

[akeller]

@hamza-m-masood, can we get your review here?

[jessesimpson36]

Sorry @akeller , you'll just have to put up with a review from me 😜 .

I do not find the two statements:

(statement A)

When updating from one minor version to the next, you do not need to update to each patch version along the way. However, do not skip minor versions when updating.

and

(statement B)

The recommended upgrade path for any given installation is to the latest patch release of the next minor version.

to be contradictory. I think the difference between them is that one states what not to do, and the other describes what to do. And I think both are clear that one minor upgrade at a time is the acceptable approach.

However, one thing that I'm realizing is that the "meaning" of a minor version is different now that we have the detached version numbers. We should re-think whether this statement is intended for people thinking about the camunda version numbers or the helm chart version numbers. if it's the helm chart version numbers, we need to say

Suggested change

	:::note
	The recommended upgrade path for any given installation is to the **latest patch** release of the **next minor version**.
	:::note
	The recommended upgrade path for any given installation is to the **latest patch** release of the **next major version**.

[akeller]

@jessesimpson36 appreciate you 🙂

Great point about the detached version numbers. The only additional thing I would add to your suggestion is to qualify that this is for Helm charts.

@conceptualshark can you have a look at this feedback and adjust the PR?

[conceptualshark]

@jessesimpson36 @akeller The original request is here - I was making the assumption it meant camunda versions, but documented on the Helm chart page. Would it be appropriate to update this note to include a specific recommendation for each?

[akeller]

I'm good with saying this page refers to major versions because we are within the context of Helm. So, we recommend the latest patch release of the next major version (of the Helm chart). I would rather not go into more detail about each. If we get more feedback on this page, we can always adjust it.

[jessesimpson36]

I'm reviewing this now

[jessesimpson36]

I'm good with this change. I feel my comment left some points that were out of the scope of this PR, so I will approve now, and if you want to continue discussion on those points before merge, we can at your discretion.