# Upgrading

Read the sections of the [changelog](./changelog.md) between your release and the new one. A change that needs edits to application or project files states them. Then run these steps in the module root.

1. Install the new CLI and check its version:

   ```sh
   go install github.com/romshark/datapages/cmd/datapages@latest
   datapages version
   ```

2. Update the module. `go get` also raises the requirements that Datapages depends on, such as `github.com/a-h/templ`. Without this step, the first `datapages gen` can fail with `go: updates to go.mod needed`:

   ```sh
   go get github.com/romshark/datapages@latest
   go mod tidy
   ```

3. Install the templ CLI of the templ version that `go.mod` now requires:

   ```sh
   go install github.com/a-h/templ/cmd/templ@$(go list -m -f '{{.Version}}' github.com/a-h/templ)
   ```

4. Regenerate the code. Code generated by an older release may not compile with the new runtime until `datapages gen` replaces it:

   ```sh
   templ generate
   datapages gen
   ```

5. Update the instructions for coding agents, as [AI agents](./ai-agents.md) describes:

   ```sh
   datapages init -n
   ```

6. In `.github/workflows/ci.yml`, change the versions in the `go install github.com/romshark/datapages/cmd/datapages@` and `go install github.com/a-h/templ/cmd/templ@` steps to the versions in `go.mod`. `init` does not rewrite the workflow. With the old versions, CI fails with `go.mod requires github.com/romshark/datapages ... but you are running ...` or `templ generate produced uncommitted changes`.

7. If the app uses the offline module, increment `offline.Config.WorkerVersion`, as [Keep snapshots safe and current](./offline.md#keep-snapshots-safe-and-current) describes.

8. Check the application:

   ```sh
   datapages lint
   go build ./...
   go test ./...
   ```

Then deploy the new build.

## Version policy

Datapages is in beta and ready for production use. Its APIs can still change in a release. The public API includes the root `datapages` package, packages under `modules/` and generated packages such as `href` and `action`. The changelog lists each incompatible change under Changed or Removed and gives the required steps.

Packages under `runtime/` serve generated code and may change in any release. `datapages gen` updates their callers. The CLI rejects imports of these packages from application code.

[SECURITY.md](https://github.com/romshark/datapages/blob/v0.11.2/SECURITY.md) states which releases receive security fixes.

## See also

- [Changelog](./changelog.md): every change of each release and the steps it needs
- [CLI](./cli.md): the version checks and the update check
- [AI agents](./ai-agents.md): what `datapages init -n` rewrites and keeps
- [SECURITY.md](https://github.com/romshark/datapages/blob/v0.11.2/SECURITY.md): supported releases and how to report a vulnerability
- [Installation](./installation.md): the tools and their versions