plain-upgrade_skill

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