Releases and stability

The current release is v0.2.4. The dev documentation describes the latest code on main, which may include changes not yet released; the versioned documentation matches each release exactly.

#Is Cicadel ready to use?

Yes, for building applications. v0.2.4 contains the core of a web framework, and 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;
• GORM models with recorded, reviewable PostgreSQL migrations and typed queries;
• typed .templ components, Tailwind CSS and htmx;
• 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.

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

Not part of 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.

Cicadel has not had an outside security audit, and the owners decided not to make one a release requirement. Security features are covered by automated tests. If you deploy publicly, review your own application’s threat model.

#Stability guarantee

From v0.1.0, releases follow semantic versioning. The root module and the four core modules (contrib/accounts, contrib/formsets, contrib/migrations and contrib/querygen) are released together with the same version. Use the same version for all of them.

• Patch releases (v0.2.1, v0.2.2 …) contain fixes and backward-compatible additions. They never break the stable surface below. Upgrade with go get github.com/fauzaanu/cicadel@v0.2.x and the matching core module versions.
• Minor releases (v0.3.0 …) mark a completed milestone (see versioning standard). Before v1.0 a minor release may also change the stable surface when necessary. Every such change is listed under Breaking changes in the changelog with exact upgrade steps. Where practical, the old API keeps working for one more minor release and is marked // Deprecated: with its replacement.
• v1.0 and later: no breaking changes within a major version.

The stable surface is:

• 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 by 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, and performance characteristics. Security fixes may change behavior that was itself insecure; such changes are called out in the changelog.

#Versioning standard

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

Choosing the next version

Rules:

• Bump the minor version only when the current milestone below is complete. Never bump it for a single feature, and 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. A patch with only documentation or test changes is not needed.

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.4 startproject myapp example.com/myapp

The repository is private: set GOPRIVATE=github.com/fauzaanu/cicadel and configure Git credentials with access first. The generated go.mod pins the framework and core modules at the CLI’s release. Upgrade an application by moving all five modules to the new version together:

v=v0.2.4
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

Read the changelog entry first, apply listed upgrade steps, then 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.

If step 6 fails, fix it and release the next patch version; never move a published tag.

#Requirements

Use Go 1.26.11 or later in the 1.26 series and PostgreSQL 18. Keep the CLI and application on the same framework revision, and commit go.mod and go.sum.

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 migration and query-generation module versions; new projects pin accounts and formsets as well. Run integration checks in every module and verify a generated project with GOWORK=off and no local replacements before updating those pins. 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 manually invoked draft-release workflow requires root CI, accounts, formsets, migration/query-generation installables, and documentation verification to pass before building CLI archives. A failure in any suite prevents artifact creation. Documentation verification in this workflow does not publish the website.

Select the workflow revision matching the existing semantic-version tag. The build job verifies that the tag resolves to the same commit checked by the reusable workflows before compiling Linux/macOS amd64/arm64 binaries and checksums. A tag pointing elsewhere fails closed; rerun against the correct revision. Draft creation is not publication; publish the draft as described in the release procedure.