home / skills / dropseed / plain / plain-upgrade

plain-upgrade skill

safe

This skill assists you upgrade Plain packages, apply necessary migrations, and validate changes to keep your project aligned with new versions.

npx playbooks add skill dropseed/plain --skill plain-upgrade

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

927 B

---
name: plain-upgrade
description: Upgrades Plain packages and applies required migration changes. Use when updating to newer package versions.
---

# Upgrade Plain Packages

## 1. Run the upgrade

```
uv run plain upgrade [package-names...]
```

This will show which packages were upgraded (e.g., `plain-models: 0.1.0 -> 0.2.0`).

## 2. Apply code changes for each upgraded package

For each package that was upgraded:

1. Run `uv run plain changelog <package> --from <old-version> --to <new-version>`
2. Read the "Upgrade instructions" section
3. If it says "No changes required", skip to next package
4. Apply any required code changes

## 3. Validate

1. Run `uv run plain fix` to fix formatting
2. Run `uv run plain preflight` to validate configuration

## Guidelines

- Process ALL packages before testing
- DO NOT commit any changes
- Keep code changes minimal and focused
- Report any issues or conflicts encountered

Overview

This skill upgrades Plain framework packages and guides the developer through required migration changes. It automates package version bumps, surfaces upgrade instructions, and helps you apply only the necessary code edits. Use it to keep a Plain-based project current while minimizing breakage.

How this skill works

The tool runs the Plain upgrade command to fetch and display package version changes. For each upgraded package it shows changelog upgrade instructions so you can apply only the required code edits. After edits, it runs formatting and preflight checks to validate the project state.

When to use it

Preparing to move a project to newer Plain package versions
After updating dependency constraints in pyproject or requirements
Before running tests that must target the new package behavior
When a security or bug-fix release is available for Plain packages
When performing routine dependency maintenance for a Plain app

Best practices

Upgrade all Plain packages first, then make code changes to avoid partial migrations
Run uv run plain changelog <package> --from <old> --to <new> for each upgraded package and follow the Upgrade instructions section
Keep code changes minimal and scoped to the breaking changes noted in the changelog
Do not commit changes mid-process — finish all package updates and validation before committing
Run uv run plain fix then uv run plain preflight to ensure formatting and configuration are correct

Example use cases

Updating plain-models from 0.1.0 to 0.2.0 and applying API changes shown in the changelog
Bulk upgrading several Plain packages after a framework minor release and validating the app with preflight checks
Fixing breaking changes introduced by a new Plain router or middleware package following the changelog guidance
Performing a controlled upgrade for a production release window where minimal, reviewable edits are required

FAQ

Can I upgrade packages one at a time?

You can, but the recommended flow is to upgrade all packages first and then apply changes. This avoids interdependent partial migrations.

What if the changelog says "No changes required"?

Skip code edits for that package and proceed to the next upgraded package. Still run formatting and preflight checks after all upgrades.