Update release process #1356

duglin · 2025-07-23T19:51:07Z

create a new branch for each release instead of a tag/github-release

duglin · 2025-07-23T19:51:18Z

- create a new branch for each release instead of a tag/github-release Signed-off-by: Doug Davis <[email protected]>

duglin · 2025-07-30T18:04:18Z

ping @jskeet I updated the process - see what you think

jskeet

As mentioned, I think "here's what we're trying to do" and "here's how to achieve it as a list of steps" should be separate, and we should talk about whether we need different branch and tag names. Happy with the overall approach though.

jskeet · 2025-07-31T07:15:12Z

docs/GOVERNANCE.md

+  Git branches will be used as a way to snapshot/tag releases. While we hope
+  to not push new commits to these branches, in practice, it is possible that
+  changes to a release might be needed without "picking up" other changes that
+  might have been commited to "main". Creating the branch during the release


Suggested change

might have been commited to "main". Creating the branch during the release

might have been committed to "main". Creating the branch during the release

delete para

jskeet · 2025-07-31T07:15:42Z

docs/GOVERNANCE.md

+  to not push new commits to these branches, in practice, it is possible that
+  changes to a release might be needed without "picking up" other changes that
+  might have been commited to "main". Creating the branch during the release
+  process will makes this easier to manage should the need should arise.


Suggested change

process will makes this easier to manage should the need should arise.

process makes this easier to manage should the need should arise.

delete para

jskeet · 2025-07-31T07:17:25Z

docs/GOVERNANCE.md

+  - Merge the PR.
+  - Initiate a final review/test of the release.
+
+- A "release candidate" tag will be created with the new release version


I thought we weren't going to use tags at all, on the grounds that we'd need to keep the tag up-to-date with the branch?

I think using tags for RC makes since so that people can have a stable version of the repo to look at. I guess we could just tell people to always look at the latest stuff on "main" if you don't see value in it. I envision this RC tag only being useful during the review cycle. We could even delete it when done if we want to clean things up.

Another alternative would be to create the branch at the point of release candidacy (but not the tag) and refer people to the branch? That would allow "things for past that version" to happen on main (good) but mean duplication of changes for that version (bad).

The original comment was left over from my first 5 minutes of review, where I hadn't got to grips with the idea of "we'll use both". I'm okay to go with a tag for RCs - just thought I'd mention the branch alternative for discussion.

yea, I'm not thrilled with the idea of dual maintenance once an RC is created. If the RC lives for a long time that's just going to be annoying. If you think having an RC tag is bad, or confusing, then I'm ok with just telling people to look at the tip of "main" for their review.

jskeet · 2025-07-31T07:21:18Z

docs/GOVERNANCE.md

-  Make sure to remove `-wip` from all of the version strings.
+
+- For the most part we try to only use a single branch ("main") for our work.
+  Git branches will be used as a way to snapshot/tag releases. While we hope


I suggest we separate "the process" from "the motivation/reasoning".

I think it's worth calling out something like: "Each full (non-RC) release will have both a tag and a branch. The tag will be kept up-to-date with the tip of the branch. The purpose of having a branch is to support very minor fixes (typos, clarifications) which amend a release in place. The purpose of having a tag is to support GitHub releases, which can act as a notification channel for interested users."

Copied your proposed text into the previous section - and deleted this paragraph

jskeet · 2025-07-31T07:23:39Z

docs/GOVERNANCE.md

+  - Update the appropriate `*/RELEASE_NOTES.md` file with the changes
+    for the release. The list can be generated via:
+    `git log --pretty=format:%s main...v0.1 | grep -v "Merge pull"`
+    by replacing "v0.1" with the name of the previous release. Or, use github's


Probably best to give a fuller example, e.g. cloudevents/v1.0.4 here.

jskeet · 2025-07-31T07:26:20Z

docs/GOVERNANCE.md

+  - `git tag -d vX.Y.Z` to delete the old tag for the release
+  - `git tag vX.Y.Z vX.Y.Z-branch` to create a new tag for the HEAD of the
+    release branch
+  - `git push REMOTE vX.Y.Z -f` to force the tag to updated in the github repo


Suggested change

- `git push REMOTE vX.Y.Z -f` to force the tag to updated in the github repo

- `git push REMOTE vX.Y.Z -f` to force the tag to updated in the GitHub repo

jskeet · 2025-07-31T07:32:20Z

docs/GOVERNANCE.md

+
+- If an update to a release is needed, create a PR for the appropriate
+  branches (including "main"), and merge when ready. For any release that's
+  updated, you'll need to move the tag for that release to point to the HEAD


I think when referring to it normally, this should be head (or tip) rather than HEAD. I think HEAD is just the committish you can use in git commands.

Suggested change

updated, you'll need to move the tag for that release to point to the HEAD

updated, you'll need to move the tag for that release to point to the head

jskeet · 2025-07-31T07:32:56Z

docs/GOVERNANCE.md

+  it but for now you can do it via the CLI:
+  - `git pull` to make sure you have all latest branches and tags
+  - `git tag -d vX.Y.Z` to delete the old tag for the release
+  - `git tag vX.Y.Z vX.Y.Z-branch` to create a new tag for the HEAD of the


Suggested change

- `git tag vX.Y.Z vX.Y.Z-branch` to create a new tag for the HEAD of the

- `git tag <subject>/vX.Y.Z <subject>/vX.Y.Z-branch` to create a new tag for the head of the

jskeet · 2025-07-31T07:33:07Z

docs/GOVERNANCE.md

+  of that branch. We'll eventually setup a Github action to automatically do
+  it but for now you can do it via the CLI:
+  - `git pull` to make sure you have all latest branches and tags
+  - `git tag -d vX.Y.Z` to delete the old tag for the release


Suggested change

- `git tag -d vX.Y.Z` to delete the old tag for the release

- `git tag -d <subject>/vX.Y.Z` to delete the old tag for the release

jskeet · 2025-07-31T07:33:38Z

docs/GOVERNANCE.md

+  updated, you'll need to move the tag for that release to point to the HEAD
+  of that branch. We'll eventually setup a Github action to automatically do
+  it but for now you can do it via the CLI:
+  - `git pull` to make sure you have all latest branches and tags


Suggested change

- `git pull` to make sure you have all latest branches and tags

- `git pull --tags` to make sure you have all latest branches and tags

Signed-off-by: Doug Davis <[email protected]>

docs/GOVERNANCE.md

jskeet

Looking at the list of steps, I wonder whether these might actually be better as subsections with subheadings:

Creating a release candidate
Creating a final release
Updating a release

... each with a list of steps. I'm happy to give that a go after this has gone in.

A few suggestions, but I'm basically happy... and again, I could potentially apply those suggestions in a follow-up PR.

jskeet · 2025-08-01T08:37:59Z

docs/GOVERNANCE.md

-  allow for broader testing before it promoted to its final version number.
-  This will be true for updates to existing specifications and for new
-  specifications.
+- The versioning scheme used will follow [semver](https://semver.org/).


Not blocking for this PR, but we could probably change all of this into the present tense now.

got this one

jskeet · 2025-08-01T08:39:15Z

docs/GOVERNANCE.md

+- Specifications will be grouped into logical units and released at the same
+  time, with the same version number. This is true regardless of whether each


Suggested change

- Specifications will be grouped into logical units and released at the same

time, with the same version number. This is true regardless of whether each

- Specifications will be grouped into logical units, with all documents in a group released at the same

time, with the same version number. This is true regardless of whether each

jskeet · 2025-08-01T08:41:23Z

docs/GOVERNANCE.md

+  - Merge the PR.
+  - Initiate a final review/test of the release.
+
+- Create A "release candidate" with the new release version string but with a


Suggested change

- Create A "release candidate" with the new release version string but with a

- Create a "release candidate" with the new release version string but with a

jskeet · 2025-08-01T08:42:15Z

docs/GOVERNANCE.md

+  - Merge the PR.
+  - Initiate a final review/test of the release.
+
+- Create A "release candidate" with the new release version string but with a


It's not clear what "create a release candidate" actually means. What's the concrete step here? Should the "Create a PR" step above actually be a sub-bullet of this one?

I'm reworking this section a bit and I think it'll address your concerns

docs/GOVERNANCE.md

jskeet · 2025-08-01T08:44:42Z

docs/GOVERNANCE.md

+  - Use GitHub to create a
+    [new release](https://github.com/cloudevents/spec/releases/new).
+    During that process, create a new tag with the new release version
+    string (e.g. `<subject>/vX.Y.Z`) without any suffix.


Suggested change

string (e.g. `<subject>/vX.Y.Z`) without any suffix.

string in the format `<subject>/vX.Y.Z` without any suffix.

(Or keep it parenthesized but remove the e.g., as it's not really an example.)

went with:

string in the format [email protected].

duglin · 2025-08-14T16:06:21Z

@jskeet I think I got all of your suggestions. Any chance of one final review before I merge?

jskeet · 2025-08-14T16:06:55Z

@jskeet I think I got all of your suggestions. Any chance of one final review before I merge?

Will have a look through it tomorrow morning UK time.

jskeet

One tiny typo, but other than that I think we're good to go - thanks for being patient :)

jskeet · 2025-08-15T07:50:16Z

docs/GOVERNANCE.md

+- Before a new release is finalized, a "release candidate" (rc) should be
+  created that identifies the versions of files in the repository that are to
+  be reviewed. The process for a RC is as follows:
+  - Create a PR (for the "main" branch") that modifies the appropriate files


Suggested change

- Create a PR (for the "main" branch") that modifies the appropriate files

- Create a PR (for the "main" branch) that modifies the appropriate files

Got it.
Thanks for the review and time!

Signed-off-by: Doug Davis <[email protected]>

duglin · 2025-08-15T14:06:20Z

Agreed on last week's call - merging!

Update release process

177d4fe

- create a new branch for each release instead of a tag/github-release Signed-off-by: Doug Davis <[email protected]>

duglin force-pushed the releases branch from 07d7c76 to 177d4fe Compare July 30, 2025 18:03

jskeet reviewed Jul 31, 2025

View reviewed changes

more edits

6749e1f

Signed-off-by: Doug Davis <[email protected]>

duglin force-pushed the releases branch from 3a1aacb to 6749e1f Compare July 31, 2025 11:57

duglin commented Jul 31, 2025

View reviewed changes

docs/GOVERNANCE.md Show resolved Hide resolved

jskeet approved these changes Aug 1, 2025

View reviewed changes

jskeet approved these changes Aug 15, 2025

View reviewed changes

more review edits

40cda2e

Signed-off-by: Doug Davis <[email protected]>

duglin force-pushed the releases branch from e5b7df4 to 40cda2e Compare August 15, 2025 14:04

duglin merged commit 4ad3223 into cloudevents:main Aug 15, 2025
2 checks passed

duglin deleted the releases branch August 15, 2025 14:06

	might have been commited to "main". Creating the branch during the release
	might have been committed to "main". Creating the branch during the release

	process will makes this easier to manage should the need should arise.
	process makes this easier to manage should the need should arise.

	- `git push REMOTE vX.Y.Z -f` to force the tag to updated in the github repo
	- `git push REMOTE vX.Y.Z -f` to force the tag to updated in the GitHub repo

	updated, you'll need to move the tag for that release to point to the HEAD
	updated, you'll need to move the tag for that release to point to the head

	- `git tag vX.Y.Z vX.Y.Z-branch` to create a new tag for the HEAD of the
	- `git tag <subject>/vX.Y.Z <subject>/vX.Y.Z-branch` to create a new tag for the head of the

	- `git tag -d vX.Y.Z` to delete the old tag for the release
	- `git tag -d <subject>/vX.Y.Z` to delete the old tag for the release

	- `git pull` to make sure you have all latest branches and tags
	- `git pull --tags` to make sure you have all latest branches and tags

		- Specifications will be grouped into logical units and released at the same
		time, with the same version number. This is true regardless of whether each

	- Create A "release candidate" with the new release version string but with a
	- Create a "release candidate" with the new release version string but with a

	string (e.g. `<subject>/vX.Y.Z`) without any suffix.
	string in the format `<subject>/vX.Y.Z` without any suffix.

	- Create a PR (for the "main" branch") that modifies the appropriate files
	- Create a PR (for the "main" branch) that modifies the appropriate files

Update release process #1356

Update release process #1356

Uh oh!

Conversation

duglin commented Jul 23, 2025

Uh oh!

duglin commented Jul 23, 2025

Uh oh!

duglin commented Jul 30, 2025

Uh oh!

jskeet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jskeet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment