# Upgrade Wagtail to the Latest Release

An agent checks Wagtail and Django compatibility, updates the site's requirements, and returns an upgrade PR with system and test output.

[Run this on Rush](https://cloud.getrush.ai/run/upgrade-wagtail/wagtail/), in a Project that has your repository.

## What the agent does

The agent first identifies which requirement files actually control the site. In wagtail/bakerydemo, requirements.txt includes requirements/production.txt, which includes requirements/base.txt. The base file specifies Django>=6.0,<6.1 and wagtail>=8.0,<8.1. Development tools live in requirements/development.txt instead. The agent follows those includes, records the installed baseline and reads the relevant Wagtail upgrade notes. Latest compatible means compatible with the site's declared release ranges unless you explicitly ask it to widen them.

It installs the development requirements in an isolated Python environment and uses the repository's test settings. .github/workflows/ci.yml sets DJANGO_SETTINGS_MODULE=bakerydemo.settings.test before running manage.py check, makemigrations --check --noinput and manage.py test. The test settings choose StaticFilesStorage, local-memory caching and immediate background tasks. The agent preserves that setup so a missing collected-static manifest or unrelated cache service does not get confused with a framework regression.

It updates the compatible Wagtail and Django packages with pip, then checks the site and its model migrations before running python manage.py test. bakerydemo/base/tests/test_home_page.py builds a page tree, publishes a HomePage and checks rendered hero content as well as editor creation. Those tests matter because a dependency update must leave page rendering and Wagtail's editor-facing forms intact. The agent inspects affected models, templates and settings when upgrade notes require an application adjustment rather than assuming installation is enough.

A failing candidate is investigated before it is included. The agent separates a dependency conflict from a system-check failure, an unexpected migration and a failing page test. It leaves out incompatible upgrades and explains why, without removing requirements or weakening assertions just to obtain green output. If the newest Wagtail release needs a Django or Python series outside the current policy, the result identifies that boundary and keeps a larger migration out of the weekly update.

## Start it with one API call

`POST https://api.prix.dev/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Upgrade Wagtail and Django to the latest versions compatible with this site's current requirements and Python runtime. Trace requirements.txt and its includes, read the relevant Wagtail upgrade notes and establish the existing test baseline. Use pip in an isolated environment and the repository's test settings. Run python manage.py check, python manage.py makemigrations --check --noinput and python manage.py test. Include only upgrades that pass these checks; leave out incompatible candidates and explain the exact failure. Do not weaken tests, edit demo content unnecessarily or cross release-series constraints without approval. Open a pull request with one line per retained bump and the verification output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.prix.dev/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The upgrade pull request changes the requirement declarations that need changing and includes any required compatibility edits to site code. The summary lists the old and proposed Wagtail and Django versions, the upgrade notes considered, and the system-check, migration-check and test commands. Candidates left out have their own explanation. A claim that pip found a valid installation remains distinct from a claim that the site's tests pass.

Reviewers check whether a requirement range was widened, whether the supported deployment environment can install the proposed versions, and whether any generated migration is genuinely required. They inspect editor and template changes rather than treating them as dependency noise. The result also states what still needs browser review: a passing page-render test does not prove that every StreamField editing interaction or custom admin extension behaves correctly.

## Run it on every Wagtail maintenance window

Your maintenance scheduler can start one session per site by sending this request to the sessions API. Replace the resource URL with a repository covered by your Rush GitHub App installation. Keep each site's supported release policy in its prompt or repository instructions. Read the finished session's result and PR before scheduling a wider migration, so repeated maintenance runs do not quietly expand into repeated major-version attempts.

## Why run it on Rush?

Wagtail maintenance involves the Python environment, Django settings, database schema and rendered pages together. Rush gives the agent a separate sandbox for those checks rather than asking a developer to switch a working site between dependency candidates. The test settings and database used in the investigation can be recorded alongside the proposed requirement changes.

That record helps a reviewer distinguish framework incompatibility from local setup problems. Rush exposes the transcript's tool calls and results, so the failed migration check or page assertion behind an omitted bump remains inspectable. Several sites can be examined in separate sessions without mixing their settings modules, temporary databases or upgrade decisions.

## Frequently asked questions

### Does latest release mean a major-version migration?

This request stays within the site's declared compatibility ranges. The inspected example constrains both Wagtail and Django to particular release series in requirements/base.txt. If reaching a newer series requires widening those constraints, ask for that migration explicitly and review its code and data implications separately.

### Which requirements file will it edit?

The agent traces the includes before editing. In the demo, framework constraints belong to requirements/base.txt, while requirements.txt enters through the production requirements. It should update the owning declaration instead of adding a second conflicting requirement in a different file.

### Will it generate or apply production migrations?

No production database is part of this request. The agent checks migrations and runs the tests in the sandbox. If an upgrade genuinely needs a migration, that change and its deployment implications belong in the pull request for a reviewer to approve.

### Can the tests catch broken Wagtail page rendering?

They can catch the rendering behaviors they exercise. The demo's HomePage test publishes a page and asserts its template and hero content, which makes those useful checks during an upgrade. Custom blocks, admin widgets and visual layout may need additional tests or browser review rather than an unsupported claim of complete coverage.