Skip to content

Notes for project maintainers

Jump to bottom
Roger Peppe edited this page Jun 14, 2024 · 31 revisions

Below is a random collection of notes for project maintainers.

Releases

Release branches

Feature releases such as v0.7.0 are typically tagged from master, which is frozen to prevent new features around the time the first release candidate is out. Once the final release is out, master can optionally stay frozen for a few weeks if we already anticipate a follow-up bugfix release like v0.7.1. Once development in master begins for the next feature release, its following commit should be tagged like v0.8.0-0.dev, to ensure that the master commits developing the next feature release v0.8 don't get semver pseudo-versions such as v0.7.1-timestamp-commit, which would be considered as a lower version compared to any further v0.7.x bugfix releases.

Once master is open for development of the next feature release, any further bugfix releases should come from a release branch where we backport fixes to via cherry-pick CLs. To use such a branch, remember that:

  • The branch should have the prefix release-branch., such as release-branch.v0.7, to trigger CI properly
  • Just like creating tags, creating the branch should be done via the Gerrit UI by a CUE Super Admin, starting at a tag like v0.7.0
  • Typically, CLs will be backported from master to the release branch via the "Cherry pick" button at the top right of the Gerrit UI
  • Manual cherry-picking can also be done locally via git, for example to resolve conflicts - as long as the Change-Id trailer is deleted and re-generated, to mail a new CL against the release branch
  • When no more bugfix releases will be done, the release branch should be deleted via the Gerrit UI

Note that Gerrit only exposes git tags which are reachable from exposed git branches for security reasons. If a release is tagged from a release branch, simply deleting the release branch would hide the release's git tag moving forward, breaking users. For that reason, before deleting e.g. refs/heads/release-branch.v0.7, a CUE Super Admin should create the branch refs/attic/release-branch.v0.7, which is public and ensures reachability is maintained, but is not shown in the refs/heads/* branch list.

Doing a release

Steps to do before tagging a release:

  • If tagging from master:
    • Update important dependencies like cuelabs.dev/go/oci/ociregistry and golang.org/x/tools/...
    • Check that updating go.mod in cuelang.org to the latest master commit does not cause any breakage
  • Check that updating site.cue in cuelang.org to the commit about to be tagged does not cause any breakage
  • Update ./internal/ci/repo.pinnedReleaseGo to build release binaries with the latest version of Go
  • If tagging a non-prerelease release, update cueversion.LanguageVersion to the next version non-prerelease version that will be tagged
  • Draft the release notes

Note that the Goreleaser setup and config are only minimally tested via CI before and after each commit is merged. For any non-trivial changes before a release, consider tagging a version such as v0.0.0-goreleaser.202211181000 to double check that it still succeeds on a tag release.

A release is created by creating a semver tag in the GerritHub repository as a member of the CUE Super Admins group, such as Chief Cueckoo. This is most simply done via the Gerrit tag UI. This tag will then replicate to GitHub, at which point the release workflow will be triggered. This workflow is responsible for creating the release assets, Docker images etc.

Steps to do after tagging a release:

  • If tagging unfreezes master for feature work, make a new master commit and tag it with a -0.dev version as described above, and update cueversion.LanguageVersion to the next minor version, e.g. v0.10.0.
  • If tagging from master, actually update cuelang.org to use the new semver version for all documentation
  • Update our services repo to the latest master commit, to ensure it supports modules published with the version being published
  • Update site.cue in cuelang.org to use the newly tagged version
  • Edit the GitHub release draft created by Goreleaser with the release notes and cueckoo releaselog
  • Post on Slack (#general, #announcements), Discord (#announcements), and social media (Bluesky, Twitter)

Making GerritHub config changes

Whilst some config changes can be made via the Gerrit UI, the majority cannot. Changes to Gerrit config files should be submitted for review in the usual way, but pushed for review against the meta/config branch.

Note that Gerrit exposes this branch as refs/meta/config on the remote, so git fetch will not fetch it alongside all other branches under refs/heads/* by default. The simplest solution to that is to configure your local git repository:

# Fetch all meta branches from the Gerrit "origin" remote as well.
git config --add remote.origin.fetch '+refs/meta/*:refs/remotes/origin/refs/meta/*'
# Fetch refs/meta/config for the first time.
git fetch origin

Then, send a CL like you usually would - just making sure that you start from meta/config rather than master or main.

# You can also use a similar command to create a local tracking branch, like with master or main.
git switch -c my_config_change origin/refs/meta/config

# Make config changes

git codereview change -s -a -m 'Important configuration changes'
git codereview mail

When you git codereview mail, GerritHub validates the configuration. If it is not valid for whatever reason, it will not accept the change.

Config changes can be approved by a member of the CUE Admins group but can only be submitted by a member of the CUE Super Admins group.

GitHub

The contribution guide describes the workflow for both Gerrit-based and GitHub PR-based contributions. The GerritHub repository is the source of truth for the CUE project, and as such GitHub PRs should not be merged. Rather, they must be imported via the GerritHub UI.

Pull Request workflow

Given that GerritHub is the source of truth, Pull Requests need to be imported into GerritHub to be submitted as part of the usual change workflow. It's generally easier for the contributor to participate in the Pull Request (familiar code review process), and then have a CUE approver import and submit the Pull Request when it's ready.

Note that we always try to review PR contributions directly on GitHub first. In the case where the contributor doesn't respond after a few weeks, and the adjustments needed aren't major, you can apply them yourself as long as you add yourself as a second author via git commit trailers:

Co-authored-by: Your Name <[email protected]>
Signed-off-by: Your Name <[email protected]>

To import a Pull Request, use cueckoo importpr as follows:

go install github.com/cue-sh/tools/cmd/cueckoo@latest
cueckoo importpr 123 # replacing 123 with the PR number to be imported
Clone this wiki locally