Release: the beta path, tool and rehearsal

Open
  • Is something wrong?
#132 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
15/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions, julia
Domain
ci-cd, release

Research direction

Start with the open decisions in points 3 to 5, which need maintainer input before any code. The tool lives in scripts/release/ (release.jl, with tests in scripts/release/test/runtests.jl), and the recipe is recipes/release.md. Done means register-beta is idempotent and checked, with fixture tests, and the sandbox rehearsal runs beta then stable end to end.

Written by the indexing model from the issue text.

Description

Part of the epic on releases without a local agent. The beta path of the recipe has never been run end to end: this issue lists what is covered, what is not, and a way to rehearse it without polluting the real registry.

What is covered

  • Version arithmetic (REL1, REL2, REL3): unit tests and a property test over 2000 random histories of stables and betas in scripts/release/test/runtests.jl.
  • A local dry run on CTModels (a fake 0.21.2-beta in a throwaway worktree, nothing pushed): release.jl gate checks the suffix, the triple, REL1, CHG3, REL7, the encoding and the labels for a beta; release.jl status --version 0.21.2-beta says phase 0 and "it goes to ct-registry"; release.jl register refuses a beta.
  • ReleaseTag marks a beta as a pre-release (documented in docs/workflows/release-tag.md).

What is not covered

  1. The registration in ct-registry has no tool. The recipe runs LocalRegistry by hand from a shared environment with SSH access. It is not idempotent ("ensure"), not checked afterwards, and it cannot run in a workflow as it is. Needed: a release.jl register-beta that (a) does nothing if ct-registry already holds the version, (b) registers from the merge commit, (c) checks that the registry holds the version at the tree of the tag. status already reads the registries to decide phase 8, so (c) can reuse it.
  2. Credentials for ct-registry in a workflow. LocalRegistry pushes to a private repository. Either a deploy key with write access (secret SSH_KEY), or the GitHub App of the epic installed on ct-registry (contents: write) with an HTTPS push. To verify that LocalRegistry.register works with a token, not only SSH. status and audit also need to read ct-registry with the token of the workflow.
  3. The changelog of the stable that follows betas. The tool counts the betas when it checks REL1 for a stable (the sections of the betas are read), but the registration comment and the GitHub release notes use the ## [X.Y.Z] entry of the stable alone, and REL5 wants notes since the previous stable. The recipe says past entries are never edited. So the entry of the stable must repeat what the betas brought, or the tool must build the notes from all the sections since the previous stable. A decision, and maybe a gate check (the stable entry covers the sections of the betas).
  4. What the gate asks of a beta. The dry run showed CHG2 (the entry needs a ### ✅ Compatibility subsection) and REL7 (a change under src/, ext/, docs/) apply to a beta too. Probably right, but to confirm that it is wanted for a beta that only exists to test a dependent.
  5. The documentation of a beta tag. ReleaseTag runs the documentation workflow on the tag; whether a pre-release tag is deployed, and where (a folder per beta, or the dev one), is not documented.
  6. A beta that must be replaced. A tag, a pre-release and a ct-registry entry are never reused (REL2: a new triple). The recipe has no step for a beta found broken after the registration: the next beta is the only remedy; to write down.
  7. The autonomous and the supervised modes for a beta. The checkpoints are the same minus the registration comment (there is none for a beta), so the supervised mode stops twice, not three times. The workflow of the epic must handle both.

Rehearse without polluting ct-registry

A beta leaves permanent traces: a tag, a pre-release, an entry in ct-registry, a consumed triple. Rehearse on a sandbox package (a throwaway repository with a trivial package and the standard callers) and a sandbox registry (a copy of ct-registry's structure), through the whole chain, beta then stable:

  • the release tool on the sandbox (gate, ready, merge, register-beta, status, audit);
  • the finish workflow of control-toolbox/CTActions#128, with the App and the Environments;
  • the stable that follows the beta (the changelog and the notes of point 3).

This is also the integration test of the whole finish workflow, for both kinds, before the first real use.

Tasks

  • Decide points 3 to 5; write them in ct-conventions (changelog.md, release.md) and in the recipe.
  • release.jl register-beta (idempotent, checked), with tests on fixtures.
  • Credentials for ct-registry in a workflow (key or App), and read access for status and audit.
  • A sandbox package and registry; run beta then stable on them.
  • Update recipes/release.md (beta, modes) from what the rehearsal shows.
Dominant language
Julia
Stars
1
Forks
0
Avg merge
1h 39m
Merged PRs (30d)
45

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from control-toolbox/CTActions

All issues in control-toolbox/CTActions

Similar issues

More Julia issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.