chore: add docs about release branches and how to release a new version

[yordis]

Description of your changes

Fixes #

I have:

• Read and followed Crossplane's contribution process.
• Run make reviewable test to ensure this PR is ready for review.

How has this code been tested

[jbw976]

Great initiative to document this process for this provider @yordis! really appreciate you always willing to do that 🙇‍♂️

I've made a few clarification comments here that we can continue discussing as needed :)

[yordis]

@jbw976 I updated the docs. However, I am lost as to how to backport (whatever that means) into the release branch when I work in the trunk branch.

The marketplace already supports full SemVer vMAJOR.MINOR.PATCH tagging, so I do not understand why the release—* is only MAJOR.MINOR; ideally, they should be immutable.

There is a solid release to have the existing workflow, but, as an outsider, I don't see the value of the situation being honest with you.

[jbw976]

The marketplace already supports full SemVer vMAJOR.MINOR.PATCH tagging, so I do not understand why the release—* is only MAJOR.MINOR; ideally, they should be immutable.

There is a solid release to have the existing workflow, but, as an outsider, I don't see the value of the situation being honest with you.

At the end of the day, you're the maintainer for this provider, so you can choose to run it how you see fit. I'm just sharing with you the processes we've developed over the years while maintaining multiple repos/projects across the Crossplane ecosystem - you can make the final call on the process you want to run for this repo 😉

The main point of a minor release branch is so you have a historical point in time on which to service with fixes and patches. So when you create the release-0.2 branch, you'll apply the v0.2.0 tag to the HEAD commit of that branch. That will be the v0.2.0 release - the release build runs on that tag/commit, and it is immutable and will never change in the future.

However, what happens when there is a bug or multiple bugs you need to fix in that release, after the main branch has already moved on? In the process and tooling we use in Crossplane, we do the following:

• get those fixes to the release-0.2 branch
  • this is done by first applying fixes to main and then backporting to the release branch so they will be fixed for the next release and for the previous release
• add a new tag v0.2.1 to the new HEAD commit of the release branch
• run a new immutable v0.2.1 build from that tag/commit.
• the process repeats for each patch release you'd like to do for the v0.2.x series.

I think the alternative in your mind is to create a release branch (or maybe just a tag on main) for every single patch release, e.g. release-0.2.2? The problem that runs into is when main has moved on with changes you don't want to release yet, e.g. a big feature that needs some bake time. With a historic minor release branch, you can apply JUST the bug fix for a specific bug to that release branch and run a release build that contains a new delta of only that fix - the big risky changes in main can keep baking and will not be included in the release.

This diagram may help - how would you release v0.2.1 without also releasing the big risky change?

main
| 
release-0.2.0
|
big risky change
|
fixes for v0.2.1
| 
release-0.2.1

That's probably the biggest issue I have with any approach that doesn't maintain historic release branches for previous minor releases - hopefully this explanation is helpful 🙇‍♂️

[yordis]

@jbw976 it is ready again, I think I got the workflow now

[jbw976]

Cool @yordis, thanks for taking the time to think through this release flow and the complexities of it. LGTM! 🙇‍♂️