add-ideas/govoplan-core
1
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

Release v0.1.8

Browse Source
This commit is contained in:
Albrecht Degering
2026-07-11 17:00:37 +02:00
parent a00ef54821
commit 9a0c467d55
102 changed files with 2150 additions and 9272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
docs/RELEASE_DEPENDENCIES.md
View File

@@ -16,23 +16,23 @@ resolve modules from tagged git refs or from a package registry.
Local development:
```bash
cd /mnt/DATA/git/govoplan-core
cd /mnt/DATA/git/govoplan
./.venv/bin/python -m pip install -r requirements-dev.txt
```
Release install from a core checkout plus tagged module repositories:
Release install from the meta checkout plus tagged module repositories:
```bash
cd /mnt/DATA/git/govoplan-core
cd /mnt/DATA/git/govoplan
./.venv/bin/python -m pip install -r requirements-release.txt
```
`.[server]` is resolved relative to the current working directory. If you
create the virtualenv elsewhere, still run the install command from the core
checkout:
`../govoplan-core[server]` is resolved relative to the meta requirements file.
If you create the virtualenv elsewhere, still run the install command from the
meta checkout:
```bash
cd /mnt/DATA/git/govoplan-core
cd /mnt/DATA/git/govoplan
/tmp/govoplan-release-test/bin/python -m pip install -r requirements-release.txt
```
@@ -64,9 +64,9 @@ referenced there exist, generate the committed release lockfile without
touching the development package files:
```bash
cd /mnt/DATA/git/govoplan-core
scripts/generate-release-lock.sh
cd webui
cd /mnt/DATA/git/govoplan
tools/release/generate-release-lock.sh
cd /mnt/DATA/git/govoplan-core/webui
PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run build
```
@@ -96,18 +96,18 @@ generated in a clean release workspace from tagged git dependencies.
## Release Tag Script
The normal release path is automated by `scripts/push-release-tag.sh`: it bumps
The normal release path is automated by `/mnt/DATA/git/govoplan/tools/release/push-release-tag.sh`: it bumps
or accepts the target version, updates Python/WebUI/module manifest versions,
commits/tags/pushes the module repositories first, regenerates
`webui/package-lock.release.json`, and then commits/tags/pushes core. If the
working tree has already been bumped, pass the current version explicitly:
```bash
cd /mnt/DATA/git/govoplan-core
scripts/push-release-tag.sh --version 0.1.6
cd /mnt/DATA/git/govoplan
tools/release/push-release-tag.sh --version 0.1.6
```
`scripts/generate-release-catalog.py` reads installed/discovered
`/mnt/DATA/git/govoplan/tools/release/generate-release-catalog.py` reads installed/discovered
`ModuleManifest` objects while writing catalog entries. When a manifest is
available, the catalog entry uses the manifest version, points package refs at
`v<manifest.version>`, and copies `provides_interfaces` /
@@ -157,8 +157,8 @@ running server may plan and validate package changes, but package mutation is
performed by the separate installer daemon or an operator shell during
maintenance mode.
`govoplan-web` is the public static distribution surface for official catalog
resources:
`addideas-govoplan-website` is the public static distribution surface for
official catalog resources:
- signed module package catalogs, grouped by release channel
- public catalog keyrings
@@ -423,11 +423,11 @@ Dependency vulnerability checks are documented in
[`DEPENDENCY_AUDITS.md`](DEPENDENCY_AUDITS.md). The local audit runner is:
```bash
cd /mnt/DATA/git/govoplan-core
bash scripts/check-dependency-audits.sh
cd /mnt/DATA/git/govoplan
bash tools/checks/check-dependency-audits.sh
```
The Gitea workflow in `.gitea/workflows/dependency-audit.yml` runs the same
The Gitea workflow in `govoplan/.gitea/workflows/dependency-audit.yml` runs the same
check against release dependency refs on pushes, pull requests, and a weekly
schedule.
@@ -587,22 +587,23 @@ entitlements without changing the source license of the repositories.
Production-grade distribution still needs remote registry/git artifact
resolution before package-manager apply, a hardened catalog publishing pipeline
in `govoplan-web`, and automated key rotation and emergency revocation drills.
that writes to `addideas-govoplan-website`, and automated key rotation and
emergency revocation drills.
## Release Catalog Publishing
GovOPlaN release catalogs are published by `govoplan-web` as static JSON and
verified by `govoplan-core` before installer plans are accepted. Private signing
keys must stay outside all git repositories. Public keyrings are published with
the website.
GovOPlaN release catalogs are published to `addideas-govoplan-website` as
static JSON and verified by `govoplan-core` before installer plans are
accepted. Private signing keys must stay outside all git repositories. Public
keyrings are published with the website.
Create the first catalog signing key on the release machine:
```bash
cd /mnt/DATA/git/govoplan-core
cd /mnt/DATA/git/govoplan
KEY_DIR="$HOME/.config/govoplan/release-keys"
mkdir -p "$KEY_DIR"
./.venv/bin/python scripts/generate-catalog-keypair.py \
./.venv/bin/python tools/release/generate-catalog-keypair.py \
--key-id release-key-1 \
--private-key "$KEY_DIR/release-key-1.pem" \
--public-key "$KEY_DIR/release-key-1.pub" \
@@ -612,12 +613,12 @@ mkdir -p "$KEY_DIR"
Keep `release-key-1.pem` private. The generated keyring contains only public
material.
Generate the signed catalog into `govoplan-web`:
Generate the signed catalog into `addideas-govoplan-website`:
```bash
cd /mnt/DATA/git/govoplan-core
cd /mnt/DATA/git/govoplan
KEY_DIR="$HOME/.config/govoplan/release-keys"
scripts/publish-release-catalog.sh \
tools/release/publish-release-catalog.sh \
--version <x.y.z> \
--sequence 202607071340 \
--catalog-signing-key "release-key-1=$KEY_DIR/release-key-1.pem" \
@@ -626,8 +627,8 @@ scripts/publish-release-catalog.sh \
This writes:
- `/mnt/DATA/git/govoplan-web/public/catalogs/v1/channels/stable.json`
- `/mnt/DATA/git/govoplan-web/public/catalogs/v1/keyring.json`
- `/mnt/DATA/git/addideas-govoplan-website/public/catalogs/v1/channels/stable.json`
- `/mnt/DATA/git/addideas-govoplan-website/public/catalogs/v1/keyring.json`
The wrapper validates the catalog with core using the generated public keyring.
@@ -635,14 +636,14 @@ For normal module/core releases, first audit and record migration baselines,
then tag and push the module/core repos. Finally publish the website catalog:
```bash
cd /mnt/DATA/git/govoplan-core
./.venv/bin/python scripts/release-migration-audit.py --strict
cd /mnt/DATA/git/govoplan
./.venv/bin/python tools/release/release-migration-audit.py --strict
```
```bash
cd /mnt/DATA/git/govoplan-core
cd /mnt/DATA/git/govoplan
KEY_DIR="$HOME/.config/govoplan/release-keys"
scripts/publish-release-catalog.sh \
tools/release/publish-release-catalog.sh \
--version <x.y.z> \
--catalog-signing-key "release-key-1=$KEY_DIR/release-key-1.pem" \
--build-web \
@@ -663,16 +664,16 @@ The public keyring URL is:
https://govoplan.add-ideas.de/catalogs/v1/keyring.json
```
`scripts/push-release-tag.sh` can publish the web catalog after module and core
`/mnt/DATA/git/govoplan/tools/release/push-release-tag.sh` can publish the web catalog after module and core
tags have been pushed. It runs the migration release audit in automatic mode:
warning-only before the first recorded migration baseline, strict after a
baseline exists. Add `--strict-migration-audit` when you want to force strict
mode explicitly:
```bash
cd /mnt/DATA/git/govoplan-core
cd /mnt/DATA/git/govoplan
KEY_DIR="$HOME/.config/govoplan/release-keys"
scripts/push-release-tag.sh \
tools/release/push-release-tag.sh \
--bump subversion \
--strict-migration-audit \
--publish-web-catalog \
@@ -684,6 +685,50 @@ Use `--catalog-signing-key` more than once during a key rotation window. The
catalog will contain multiple signatures and the public keyring will include the
corresponding public keys.
## Release Doctor
Use `/mnt/DATA/git/govoplan/tools/release/release-doctor.py` before release preparation and again before
publishing. It inspects repository state, local versions, release tags,
migration audit state, release package refs, stable catalog/keyring state, and
optionally public catalog availability. The default mode is read-only and
offline. Status output is intentionally concise:
```bash
cd /mnt/DATA/git/govoplan
./.venv/bin/python tools/release/release-doctor.py status --target-version <x.y.z>
```
Use `--details` when the full findings should be printed directly:
```bash
./.venv/bin/python tools/release/release-doctor.py status --target-version <x.y.z> --details
```
For concise guidance, print only suggested next commands:
```bash
./.venv/bin/python tools/release/release-doctor.py next --target-version <x.y.z>
```
For an operator-guided session, run interactive mode. The doctor asks which
suggested command to run; mutating commands require typing `RUN` before they
execute:
```bash
./.venv/bin/python tools/release/release-doctor.py interactive --target-version <x.y.z>
```
Interactive mode starts with a compact summary and waits for an action. It can
open the full report in the configured pager, run one suggested command, repair
Git `safe.directory` dubious-ownership blocks after explicit confirmation, push
all clean repositories that are ahead of their upstream, or commit and push all
dirty repositories. The dirty-repository bulk action asks for a commit message,
skips repositories that are behind upstream, and requires typing
`COMMIT AND PUSH` before it stages, commits, and pushes.
Add `--online` when remote tag and public catalog/keyring reachability should be
checked. Add `--json` when a CI job or another tool should consume the report.
On a GovOPlaN installation that should consume the official stable catalog:
```bash
@@ -707,7 +752,7 @@ operator-supervised package update with restart and health checks.
Key rotation for published catalogs:
1. Generate the next private key outside git.
2. Run `publish-release-catalog.sh` with both signing keys.
2. Run `/mnt/DATA/git/govoplan/tools/release/publish-release-catalog.sh` with both signing keys.
3. Publish the web catalog/keyring.
4. Roll the new public keyring into installations.
5. Stop signing with the old key after the supported fleet trusts the new key.
@@ -721,15 +766,15 @@ smoke check before tagging or publishing catalogs. Start the local testbed,
then run the permutation check from the core checkout:
```bash
cd /mnt/DATA/git/govoplan-core/dev/postgres
cd /mnt/DATA/git/govoplan/dev/postgres
cp .env.example .env
docker compose --env-file .env up -d
cd /mnt/DATA/git/govoplan-core
cd /mnt/DATA/git/govoplan
set -a
. dev/postgres/.env
. /mnt/DATA/git/govoplan/dev/postgres/.env
set +a
./.venv/bin/python scripts/postgres-integration-check.py \
tools/checks/postgres-integration-check.py \
--database-url "$GOVOPLAN_POSTGRES_DATABASE_URL" \
--reset-schema
```
@@ -742,56 +787,94 @@ throwaway database.
## Migration Baselines
Development migrations may be small and numerous while a feature is moving.
Before a stable release, unreleased migrations may be rewritten or squashed into
a release-level baseline or release-to-release upgrade migration. After a
release tag has shipped, released migration revision IDs are immutable.
GovOPlaN keeps those detailed migrations on an explicit development track and
publishes reviewed release shortcuts on the release track. Before a stable
release, unreleased development migrations may be squashed into a release-level
baseline or release-to-release upgrade migration. After a release tag has
shipped, released migration revision IDs are immutable.
The release policy is:
- unreleased migrations may be folded before release;
- released migrations are never rewritten or deleted;
- unreleased development migrations live in `dev_versions` and are not deleted
when a release shortcut is added;
- released migrations live in `versions` and are never rewritten or deleted;
- future release shortcuts are additive. A new release-to-release migration
starts from the previous recorded release heads, so installations can upgrade
through sane release steps instead of replaying every development revision;
- each stable release records the public migration head revisions in
`docs/migration-release-baselines.json`;
- `heads` records the Alembic dependency-leaf graph heads for a full graph,
while `owner_heads` records the latest migration revision per migration
owner for subset installs and review;
- fresh installations should apply release-level baselines/upgrades, not
unreleased create-then-rename churn;
- release-to-release schema changes should be folded into one reviewed
migration per migration owner where practical.
The default runtime track is `release`:
```bash
cd /mnt/DATA/git/govoplan
GOVOPLAN_MIGRATION_TRACK=release ./.venv/bin/python -m govoplan_core.commands.init_db
```
Use `dev` only for local/disposable development databases that intentionally
need the detailed chain:
```bash
cd /mnt/DATA/git/govoplan
GOVOPLAN_MIGRATION_TRACK=dev ./.venv/bin/python -m govoplan_core.commands.init_db
```
Production, release checks, operator install flows, and the normal development
launcher should stay on the `release` track unless a fresh/disposable database
is intentionally being used to test the detailed development chain.
Audit the current graph during release preparation:
```bash
cd /mnt/DATA/git/govoplan-core
./.venv/bin/python scripts/release-migration-audit.py
cd /mnt/DATA/git/govoplan
./.venv/bin/python tools/release/release-migration-audit.py
```
Audit the detailed development graph separately when a squash is prepared:
```bash
./.venv/bin/python tools/release/release-migration-audit.py --track dev
```
Generate the reviewed/manual squash checklist:
```bash
./.venv/bin/python scripts/release-migration-audit.py --squash-plan
./.venv/bin/python tools/release/release-migration-audit.py --squash-plan
```
After the release migrations have been reviewed and the graph is final, record
the release baseline:
```bash
./.venv/bin/python scripts/release-migration-audit.py --record-release <x.y.z>
./.venv/bin/python tools/release/release-migration-audit.py --record-release <x.y.z>
```
Use strict mode to verify that the current heads are recorded:
```bash
./.venv/bin/python scripts/release-migration-audit.py --strict
./.venv/bin/python tools/release/release-migration-audit.py --strict
```
`scripts/push-release-tag.sh` runs the audit by default in automatic mode:
`/mnt/DATA/git/govoplan/tools/release/push-release-tag.sh` runs the audit by default in automatic mode:
non-strict while no release baseline exists, strict after the first baseline is
recorded. Pass `--warn-migration-audit` for an explicit non-strict audit,
`--strict-migration-audit` to force strict mode, or `--skip-migration-audit`
only for emergency/manual release work.
Before the first stable release, fold the current development chain into the
first public baseline and record that baseline in
`docs/migration-release-baselines.json`. The tracking issue is
The first public baseline is v0.1.7. It intentionally adds release-track
shortcuts for the unreleased v0.0.0 -> v0.1.7 development chains while keeping
the detailed chains on the `dev` track. No production installations existed
before that baseline, so pre-v0.1.7 development revisions are not release
upgrade targets. Future release-to-release changes must start from a recorded
release baseline and add a new release-track step-up instead of replacing prior
release shortcuts. The tracking issue is
`add-ideas/govoplan-core#223`.
## Related Operator Documents
@@ -807,11 +890,11 @@ first public baseline and record that baseline in
- Keep Python package versions, WebUI package versions, and git tags aligned.
- Tag core, access, admin, tenancy, policy, audit, files, mail, campaign,
calendar, and scaffold module repositories together.
- Update `requirements-release.txt` and `webui/package.release.json` when the
- Update meta `requirements-release.txt` and core `webui/package.release.json` when the
release tag changes.
- Generate the committed full-product release lockfile from
`package.release.json` with `scripts/generate-release-lock.sh`.
- Run `scripts/release-migration-audit.py --strict` after recording a release
`package.release.json` with `/mnt/DATA/git/govoplan/tools/release/generate-release-lock.sh`.
- Run `/mnt/DATA/git/govoplan/tools/release/release-migration-audit.py --strict` after recording a release
baseline.
- Run the PostgreSQL release check against a disposable database.
- Publish the signed catalog through the release catalog publishing flow above.