cicadel

Releases and stability

The current release is v0.2.0. 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.0 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;
  • static files with hashed URLs, email, logging and application test helpers;
  • installable packages for your own and third-party apps.

The remaining core gaps, starting with security-header defaults, are listed in the readiness checklist; each ships in the next release once done.

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.1.1, v0.1.2 …) contain fixes only. They never break the stable surface below. Upgrade with go get github.com/fauzaanu/cicadel@v0.1.x and the matching core module versions.
  • Minor releases (v0.2.0 …) add features. 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.

#Install a release

Terminal
go run github.com/fauzaanu/cicadel/cmd/cicadel@v0.2.0 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:

Terminal
v=v0.2.0
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. 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.10 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.

Terminal
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.

View source on GitHub View as Markdown

Type to search this version.