Releases and stability

The current release is v0.2.8. This page covers what a release contains, what stays stable, how versions are chosen and how to install, upgrade and cut a release.

The dev documentation describes the latest code on main, which may include unreleased changes. Versioned documentation matches each release exactly.

#Is Cicadel ready to use?

Yes, for building applications. v0.2.8 contains the core of a web framework. Each part below is documented and tested against real PostgreSQL in freshly generated projects:

• projects, apps, typed settings, management commands, system checks and a rebuilding development server;
• routing with named URLs and reversal, request/response helpers and middleware;
• HTML error pages and panic recovery, per-route request body limits and login redirects that return users to the page they asked for;
• GORM models with recorded, reviewable PostgreSQL migrations and typed queries;
• typed .templ components, Tailwind CSS and htmx, with inline SVG, icons, typed styles, external scripts, data islands, allow-listed embeds and URL reversal inside components;
• forms, model forms, formsets and bounded file uploads;
• accounts: login, logout, password change and reset, groups and permissions, sessions and CSRF protection;
• pagination and flash messages;
• security headers, HSTS, HTTPS redirect and trusted-proxy handling;
• signed, expiring tokens with secret-key rotation;
• transactions with post-commit hooks;
• static files with hashed URLs, email, logging and application test helpers;
• installable packages for your own and third-party apps, with typed per-package settings and typed events.

Every item in the readiness checklist is released as of v0.2.4. Next is the v0.3 milestone: package-system completion, module extraction and a wider PostgreSQL migration subset.

Not in the core, and not needed to build an application: an administration interface, cache and task backends beyond the included ones, sitemaps and managed redirects. They are planned as packages after the core.

#Stability guarantee

From v0.1.0, releases follow semantic versioning.

The root module and the four core modules release together with the same version: contrib/accounts, contrib/formsets, contrib/migrations and contrib/querygen. Use the same version for all of them.

When a minor release changes the stable surface:

• the changelog lists the change under Breaking changes, with exact upgrade steps;
• where practical, the old API keeps working for one more minor release, marked // Deprecated: with its replacement.

#The stable surface

• exported Go APIs of the packages listed in the API index;
• the layout generated by startproject, startapp and startpackage;
• manage.go and cicadel command names, flags and exit codes;
• settings.Settings fields and CICADEL_* / DATABASE_URL environment variables;
• the installable-app contract (cicadel.App, Manifest, AppAPIVersion).

#Your data is always protected

• Recorded migrations and migration history written by any release keep working with every later release.
• Cicadel never requires you to edit an applied migration.
• Framework-owned tables (accounts and sessions) change only through new recorded migrations. Never through automatic or destructive schema changes.

#Not covered

• anything under internal/;
• unexported behavior;
• the exact HTML and CSS of starter and account pages;
• error message wording;
• performance characteristics.

Security fixes may change behavior that was itself insecure. The changelog calls out such changes.

#Versioning standard

Version numbers track milestones, not individual features. v1.0 arrives only when Cicadel is a complete framework.

#Choosing the next version

Rules:

• Bump the minor version only when the current milestone is complete. Never bump it for a single feature. Never release more than one minor per milestone.
• Work that would break existing applications waits for the milestone’s minor release. Until then, ship it behind a setting or as a new API, and deprecate the old one.
• Release patches as often as finished work allows. Documentation-only or test-only changes do not need a patch.

#Milestones

#v1.0 criteria

All of these must hold:

1. Every milestone above is released, giving Cicadel the capabilities of Django’s included batteries for PostgreSQL applications, or more.
2. Every exported API in the API index is documented and tested, and every capability has a tutorial or guide.
3. The owners have built and run real applications on the framework.
4. One full minor release cycle has passed with no breaking changes.

#Install a release

go run github.com/fauzaanu/cicadel/cmd/cicadel@v0.2.8 startproject myapp example.com/myapp

The generated go.mod pins the framework and core modules at the CLI’s release.

#Upgrade an application

Move all five modules to the new version together:

v=v0.2.8
go get github.com/fauzaanu/cicadel@$v \
  github.com/fauzaanu/cicadel/contrib/accounts@$v \
  github.com/fauzaanu/cicadel/contrib/formsets@$v \
  github.com/fauzaanu/cicadel/contrib/migrations@$v \
  github.com/fauzaanu/cicadel/contrib/querygen@$v
go mod tidy
go run manage.go migrate plan

1. Read the changelog entry first.
2. Apply any listed upgrade steps.
3. Run go run manage.go migrate and your tests.

#Release procedure

Maintainers and agents release completed work this way:

1. Pick the version with the versioning standard. Move the changelog’s Unreleased entries under ## vX.Y.Z — YYYY-MM-DD, with a Breaking changes list when the stable surface changed.
2. Set defaultModuleVersion in internal/scaffold/scaffold.go to vX.Y.Z, and update the current release named on this page.
3. Run every local CI check, push, and wait for the GitHub workflows to pass.
4. Tag the pushed commit for every module and push the tags: vX.Y.Z, contrib/accounts/vX.Y.Z, contrib/formsets/vX.Y.Z, contrib/migrations/vX.Y.Z and contrib/querygen/vX.Y.Z.
5. Run the Draft release workflow with the tag. It re-runs every verification workflow, builds CLI archives with checksums and creates a draft. Publish it with gh release edit vX.Y.Z --draft=false.
6. Verify a fresh project from the tag with GOWORK=off and no replace directives: startproject, go mod tidy, go test ./... and go run manage.go check.
7. Freeze the documentation for the release with python3 website/scripts/add-version.py vX.Y.Z. In the same commit, move the core modules’ requirements on each other to vX.Y.Z (GOWORK=off go get in each module, then go mod tidy), so every module builds on its own with GOWORK=off. Commit and push.

#Core and contrib release order

A contrib module can only import core APIs that exist in the core version its go.mod requires. The accounts and formsets checks type-check against that pin.

When a module needs a new core package or API:

1. Release the core change first.
2. Adopt it in the module after the freeze commit has moved the pin.
3. Release that as the next patch.

For example, v0.2.5 added events and v0.2.6 made accounts emit them.

#Requirements

• Go 1.26.11 or later in the 1.26 series.
• PostgreSQL 18.
• The CLI and application on the same framework revision. Commit go.mod and go.sum.

Check the framework version your application uses:

go list -m github.com/fauzaanu/cicadel

Start with the application tutorial. Then use the topic guides for the current model, component, form and account workflows.

#Core module composition

The root Go workspace includes the first-party modules for checkout development.

• The distributable framework pins the migration and query-generation module versions. New projects pin accounts and formsets as well.
• Before updating those pins, run integration checks in every module. Then verify a generated project with GOWORK=off and no local replacements.
• The repository is currently private. Authorized consumers need Git credentials and GOPRIVATE=github.com/fauzaanu/cicadel. CI uses its repository-scoped token through the Git credential helper.

#Release workflow details

The Draft release workflow runs only when invoked manually.

• Before it builds CLI archives, these suites must pass: root CI, accounts, formsets, migration/query-generation installables and documentation verification. A failure in any suite prevents artifact creation.
• Documentation verification in this workflow does not publish the website.
• Select the workflow revision that matches the existing semantic-version tag. The build job checks that the tag resolves to the same commit the reusable workflows checked. Only then does it compile Linux/macOS amd64/arm64 binaries and checksums.
• A tag pointing elsewhere fails closed. Rerun against the correct revision.
• A draft is not a publication. Publish the draft as described in the release procedure.