Document how to release Crossplane extensions (providers, functions, etc.)

[negz]

What problem are you facing?

The function template repos (e.g. https://github.com/crossplane/function-template-go and https://github.com/crossplane/function-template-python) set up a GitHub Action named CI. Using the Action is optional, but it can help with releasing a new function. I think it would be useful to document a release branch pattern that function authors could choose to use.

How could this Function help solve your problem?

For the functions I maintain, I first setup a https://marketplace.upbound.io repository (docs at https://docs.upbound.io):

1. Create an https://marketplace.upbound.io org and repository to match the function's GitHub org and repository. For example the org might be crossplane-contrib and the repository might be function-auto-ready.
2. Create a team with permission to write to the repository.
3. Create a robot and add it to the team.
4. Create an API token for the robot
5. Save the API token access ID as a GitHub Actions repository token named XPKG_ACCESS_ID.
6. Save the API token as a GitHub Actions repository token named XPKG_TOKEN

Once these tokens are created the CI job will push a package for every PR merged to master, using a tag like v0.0.0-20231101115142-1091066df799 as described in https://github.com/crossplane/function-template-go/pull/38.

Then, to cut a new minor version release the process is pretty simple. I:

1. Create a new branch named (e.g.) release-0.2 using the GitHub UI.
2. Create a new release named (e.g.) v0.2.0 using the GitHub UI, using the above branch. This creates a new tag.
3. Manually trigger the CI workflow against the new tag (e.g. v0.2.0) and tell it to tag the package with the same tag.

[jbw976]

This may be out of scope for the original intent of this issue, which is to document how to use the CI Action that comes from this template repo for golang functions. But i'm getting the feeling the scope of this effort could be also beneficial if it applied to the entire ecosystem of how to publish and release providers (both native and upjet) too. There's small differences between all the processes that I've firsthand seen trip some folks up over the past couple weeks.

One example is how some repos use UPBOUND_MARKETPLACE_PUSH_ROBOT_USR/UPBOUND_MARKETPLACE_PUSH_ROBOT_PSW: https://github.com/crossplane-contrib/provider-upjet-kafka/blob/main/.github/workflows/ci.yml#L264-L265

and some repos use XPKG_ACCESS_ID/XPKG_TOKEN: https://github.com/crossplane-contrib/provider-http/blob/main/.github/workflows/ci.yml#L305-L306

Another example is that the CI Action from this template repo asks you what tag to use for the package, while others infer that package tag from the github tags. Small differences have been confusing for folks, so making it clear what to do for what type of repo/package you have could be helpful. (or just unifying everything to make it consistent, but that's probably more disruptive 😂 )

[negz]

Part of the divergence is due to the complexity of the average provider vs the average function.

Few enough folks write providers that we haven't been too worried about making people learn the Upbound build submodule to do so. On the other hand, I deemed it too much for functions.

If we did want to bring the experiences closer together perhaps we could assess whether Providers could use a lighter weight CI, like functions.

[jastang]

Assuming we're leaning on upbound/build for the foreseeable future one thing that has caught community members off guard is the semver format: https://github.com/upbound/build/blob/master/makelib/common.mk#L227

It's not well-documented anywhere yet that -rc tags and whatnot won't get indexed - this applies to all Crossplane package types.

[negz]

@jastang functions don't use the build submodule, mostly they're just using multi-stage Dockerfiles.

They use go.mod style development versions - i.e. v0.0.0-<commit-timestamp>-<commit-sha>.

[yordis]

I recommend documenting and/or automating the setting of a custom rule in GitHub that ensures we can not remove the release-* branches as a safety net.

[AdamRussak]

as I'm in the process of creating a provider (I'm about to finish) ill be happy to take this Issue for the DOC but ill need some guidance @negz