RELEASING.md

Releasing CloudEvents SDK for Golang

At the time of writing, there are two major versions being releases,

• v1.+ are released from the release-1.y.z branch.
• v2.+ are released from the main branch.

General rules that apply to both releases:

• Follow semver on API changes.
• Document what is in the release.

Releasing v1.+

For v1 releases, just perform a GitHub release flow, and that is it.

Releasing v2.+

Note: What is released is controlled by hack/tag-release.sh script. Make sure the modules and go modules are up-to-date.

Using GitHub Actions,

Steps:

1. Create a branch, in the form release-v<major>.<minor>, i.e:

   branch=release-v2.1
   git checkout -b $branch
   git push -u origin $branch

   Or using the GitHub UI: search for release-v2.1 and then click create branch.

   The release workflow will automatically be run and it'll create a new Github release based on this new branch.

2. Update the release description.

   Once the new release is created, go to the Releases page and open the editor for the release notes. There should be a Generate release notes button at the top/right to auto-generate the list of PRs, new contributors and a link to the full changelog. If everything looks good, just press the Update release button at the bottom of the page.

That's it.

---

UPDATE: The following document is not required when using GitHub Actions. We will keep the process documented for manual usage of the shell script or 100% manual.

Releasing v2 is more tricky, the project has been broken into modules and are released independently but there is a dependency chain.

Note: The following steps assume the repo is checked out directly. Switch to origin to the remote name used if using a fork with a remote.

Manual Steps:

1. Create a branch, in the form release-<major>.<minor>, i.e:

   branch=release-2.1
   git checkout -b $branch
   git push -u origin $branch

2. Tag the new branch with the correct release tag, i.e:

   tag=v2.4.1
   git tag $tag
   git push origin $tag

3. Update and run ./hack/tag-release.sh to update the dependencies.

   Note: ./hack/tag-release.sh has the tag config that needs to be updated.

   Then push the changes to the release-x.y branch.

   Or do it manually with the following:

   1. Update the each protocol to use the new release rather than the replace directive in their go mod files. Example for stan:

      tag=v2.1.0
      pushd protocol/stan/v2
      go mod edit -dropreplace github.com/cloudevents/sdk-go/v2
      go get -d github.com/cloudevents/sdk-go/v2@$tag
      popd

      NOTE: to reverse the dropreplace command, run go mod edit -replace github.com/cloudevents/sdk-go/v2=../../../v2

   2. Release each protocol with a new tag that lets go mod follow the tag to the source in the form <path>/v<major>.<minor>.<patch>, i.e.:

      tag=protocol/stan/v2.1.0
      pushd protocol/stan/v2
      git tag $tag
      git push origin $tag
      popd

4. Run ./hack/tag-release.sh --tag --push to create a release of each sub-module.

   Or do it manually for each of the sub-modules with something like the following:

   tag=protocol/stan-v2.1.0
   git tag $tag
   git push origin $tag
   popd

1. Run ./hack/tag-release.sh --samples to update the sample dependencies (both the core sdk and protocol) after all releases are published. Or do it manually with something like the following:

   tag=v2.1.0
   pushd sample/stan
   go mod edit -dropreplace github.com/cloudevents/sdk-go/protocol/stan/v2
   go get -d github.com/cloudevents/sdk-go/protocol/stan/v2@$tag
   go mod edit -dropreplace github.com/cloudevents/sdk-go/v2
   go get -d github.com/cloudevents/sdk-go/v2@$tag
   popd