From bbee962ccc8fe55af1339c15f5d5f1a39871b426 Mon Sep 17 00:00:00 2001 From: Jerome Haltom Date: Sun, 18 Oct 2026 13:05:11 -0500 Subject: [PATCH 1/4] Make the README read as of a release The README still described a project that only had prereleases: its badge counted them, and Install led with --devel. Now: - The badge shows the latest stable release. - Install leads with installing the latest release, says to pin a version from the releases page, and shows how to verify the image signature rather than only pointing at the release notes. - "Project status" becomes "Releases and compatibility": where releases and their notes are, what v1 promises, that Weft itself is pre-1.0, what prereleases are for, and a pointer for upgrading from weft.run. No version number is written into the README. Versions are derived and never bumped by hand, so a literal one would be stale after the next release; the badge carries it instead. --- README.md | 48 ++++++++++++++++++++++++++++--------------- charts/weft/README.md | 7 ++++--- 2 files changed, 36 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 00a20cf..a5933cb 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@

CI - Release + Latest release License

@@ -113,13 +113,20 @@ helm install weft oci://ghcr.io/alethic/charts/weft \ --namespace weft-system --create-namespace ``` -Pin a version with `--version` for anything you care about. Builds of `main` -are also published as prereleases; add `--devel` to install the newest one. +That installs the latest release. Add `--version` with a version from the +[releases page](https://github.com/alethic/weft/releases) to pin one, which is +what you want anywhere you care about repeatability. -The controller image (`ghcr.io/alethic/weft`) and the chart are both signed -with [cosign](https://github.com/sigstore/cosign), keyless. Each -[release](https://github.com/alethic/weft/releases) lists the image digest and -the command to verify it. A released chart pins the image by digest. +Each chart pins the controller image (`ghcr.io/alethic/weft`) by digest, so an +installed release cannot drift under a moved tag. The image and the chart are +both signed with [cosign](https://github.com/sigstore/cosign), keyless, and +each release lists the image digest. To verify an image before you run it: + +```bash +cosign verify ghcr.io/alethic/weft@ \ + --certificate-identity-regexp '^https://github.com/alethic/weft/' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com +``` Every chart value is documented in [charts/weft/README.md](charts/weft/README.md), including hardening options such as confining impersonation to a set of @@ -191,17 +198,26 @@ workloads. | [Moving from weft.run](docs/migrating.md) | for installations that predate `weft.alethic.solutions/v1` | | [Security](SECURITY.md) | threat model, hardening, reporting a vulnerability | -## Project status +## Releases and compatibility + +Releases, with their notes, are on the +[releases page](https://github.com/alethic/weft/releases). The badge at the +top shows the current one. + +The API is `weft.alethic.solutions/v1`. A change that would break a `v1` +Weave would come as a new API version, not as a change to this one. + +Weft itself is pre-1.0. The controller, the chart and their defaults may still +change from one release to the next, and every such change is called out in +that release's notes. -The API is `weft.alethic.solutions/v1`. Weft itself is pre-1.0, so the -controller, the chart and their defaults may still change between minor -releases. Every such change is called out in the release notes. +Builds of `main` between releases are published too, as prereleases such as +`0.1.1-pre.3`. Helm only installs those with `--devel`; they are for trying a +fix before it is released, not for running. -Weft was first deployed under the API group `weft.run/v1alpha1`. That group is -still served alongside v1, with the same schema, so existing installations -upgrade without changing anything and can move their Weaves to v1 one at a -time. [docs/migrating.md](docs/migrating.md) explains how. Both groups are -served until a future release removes `weft.run`. +Upgrading from a build that predates `weft.alethic.solutions/v1`? Weaves in the +older `weft.run/v1alpha1` group keep working unchanged, and +[docs/migrating.md](docs/migrating.md) explains how to move them across. CI runs the reconcile loop against a real API server on Kubernetes 1.27 (the minimum supported), 1.33 and 1.37, alongside unit tests of the evaluator and diff --git a/charts/weft/README.md b/charts/weft/README.md index adbaf1d..251b9a5 100644 --- a/charts/weft/README.md +++ b/charts/weft/README.md @@ -15,8 +15,9 @@ helm install weft oci://ghcr.io/alethic/charts/weft \ ``` The chart lives in GitHub Packages as an OCI artifact. Without `--version`, -Helm resolves the newest release; pin an exact `--version` for anything you -care about. Every build of `main` is also published as a prerelease +Helm installs the latest release; pin an exact `--version` from the +[releases page](https://github.com/alethic/weft/releases) for anything you +care about. Builds of `main` between releases are published as prereleases (`0.1.1-pre.3` and so on), which Helm only considers with `--devel`. ```bash @@ -24,7 +25,7 @@ helm show chart oci://ghcr.io/alethic/charts/weft ``` The chart's `appVersion` selects the image tag, so a chart and the controller it -installs always carry the same version. A released chart additionally pins +installs always carry the same version. A published chart additionally pins the image by digest, so it cannot drift under a moved tag. That digest ships in the chart itself rather than in its values, so `helm upgrade --reuse-values` still moves you to the new release's image. From d26ab2b7ab8fbe7d180e4a21b8c3bdd85e520bb0 Mon Sep 17 00:00:00 2001 From: Jerome Haltom Date: Sun, 18 Oct 2026 13:09:17 -0500 Subject: [PATCH 2/4] Drop the pre-1.0 caveat from the README It read as a disclaimer on the release it ships with. Keep only the commitment that matters: changes are called out in release notes. --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a5933cb..e2d0de8 100644 --- a/README.md +++ b/README.md @@ -207,9 +207,8 @@ top shows the current one. The API is `weft.alethic.solutions/v1`. A change that would break a `v1` Weave would come as a new API version, not as a change to this one. -Weft itself is pre-1.0. The controller, the chart and their defaults may still -change from one release to the next, and every such change is called out in -that release's notes. +Any change to the controller, the chart or their defaults is called out in the +notes of the release that makes it. Builds of `main` between releases are published too, as prereleases such as `0.1.1-pre.3`. Helm only installs those with `--devel`; they are for trying a From 739e7cd18c88716659fa296a7d3d1512d6fa0d42 Mon Sep 17 00:00:00 2001 From: Jerome Haltom Date: Sun, 18 Oct 2026 13:09:32 -0500 Subject: [PATCH 3/4] Drop the example prerelease version from the READMEs --- README.md | 6 +++--- charts/weft/README.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e2d0de8..6994e36 100644 --- a/README.md +++ b/README.md @@ -210,9 +210,9 @@ Weave would come as a new API version, not as a change to this one. Any change to the controller, the chart or their defaults is called out in the notes of the release that makes it. -Builds of `main` between releases are published too, as prereleases such as -`0.1.1-pre.3`. Helm only installs those with `--devel`; they are for trying a -fix before it is released, not for running. +Builds of `main` between releases are published too, as prereleases. Helm only +installs those with `--devel`; they are for trying a fix before it is released, +not for running. Upgrading from a build that predates `weft.alethic.solutions/v1`? Weaves in the older `weft.run/v1alpha1` group keep working unchanged, and diff --git a/charts/weft/README.md b/charts/weft/README.md index 251b9a5..2b2ff02 100644 --- a/charts/weft/README.md +++ b/charts/weft/README.md @@ -17,8 +17,8 @@ helm install weft oci://ghcr.io/alethic/charts/weft \ The chart lives in GitHub Packages as an OCI artifact. Without `--version`, Helm installs the latest release; pin an exact `--version` from the [releases page](https://github.com/alethic/weft/releases) for anything you -care about. Builds of `main` between releases are published as prereleases -(`0.1.1-pre.3` and so on), which Helm only considers with `--devel`. +care about. Builds of `main` between releases are published as prereleases, which Helm +only considers with `--devel`. ```bash helm show chart oci://ghcr.io/alethic/charts/weft From acb13342f88e226e6f0c8ae0ead6cb9967517bd9 Mon Sep 17 00:00:00 2001 From: Jerome Haltom Date: Sun, 18 Oct 2026 13:09:59 -0500 Subject: [PATCH 4/4] Remove the release status section from the README The README describes Weft; release notes describe releases. --- README.md | 27 +-------------------------- 1 file changed, 1 insertion(+), 26 deletions(-) diff --git a/README.md b/README.md index 6994e36..383cfd2 100644 --- a/README.md +++ b/README.md @@ -195,34 +195,9 @@ workloads. | [Operating Weft](docs/operating.md) | status conditions, pruning, teardown, controller flags, metrics, uninstalling | | [Design and alternatives](docs/design.md) | how Weft compares with kro, Crossplane, Flux and Kyverno; why Starlark; non-goals | | [Helm chart](charts/weft/README.md) | installation, every value, common configurations | -| [Moving from weft.run](docs/migrating.md) | for installations that predate `weft.alethic.solutions/v1` | +| [Moving from weft.run](docs/migrating.md) | for installations that use the older `weft.run` API group | | [Security](SECURITY.md) | threat model, hardening, reporting a vulnerability | -## Releases and compatibility - -Releases, with their notes, are on the -[releases page](https://github.com/alethic/weft/releases). The badge at the -top shows the current one. - -The API is `weft.alethic.solutions/v1`. A change that would break a `v1` -Weave would come as a new API version, not as a change to this one. - -Any change to the controller, the chart or their defaults is called out in the -notes of the release that makes it. - -Builds of `main` between releases are published too, as prereleases. Helm only -installs those with `--devel`; they are for trying a fix before it is released, -not for running. - -Upgrading from a build that predates `weft.alethic.solutions/v1`? Weaves in the -older `weft.run/v1alpha1` group keep working unchanged, and -[docs/migrating.md](docs/migrating.md) explains how to move them across. - -CI runs the reconcile loop against a real API server on Kubernetes 1.27 (the -minimum supported), 1.33 and 1.37, alongside unit tests of the evaluator and -planner, rendering tests of the Helm chart, and a check that every shipped -example evaluates. - ## Contributing Issues and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers