From e6e098d4b7a7f4fde6f4285e2f9689921d6d0871 Mon Sep 17 00:00:00 2001 From: ulises-jeremias Date: Thu, 16 Jul 2026 14:09:49 -0300 Subject: [PATCH 1/2] docs: expand MIGRATION.md to CNA depth Closes #170 Co-authored-by: Cursor --- docs/MIGRATION.md | 198 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 193 insertions(+), 5 deletions(-) diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 018e370..bb99e78 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -1,7 +1,195 @@ -# Migration +# Migration Guide -From hand-rolled Cookiecutter/Copier flows: +How to keep a scaffolded project aligned with improvements in +`create-awesome-python-app` and +[cpa-templates](https://github.com/Create-Python-App/cpa-templates). -1. Map template repo to `templates.json` entry -2. Add `cpa.config.json` -3. Prefer `uv` lockfiles in generated projects +## Why migration is hard + +`create-awesome-python-app` generates a **one-time snapshot** of a template plus +extensions. After scaffolding, the CLI does not maintain a live link to your +project. You own every file and dependency choice going forward. + +That is by design -- generated projects should be independent -- but it means +updates require deliberate effort. + +## Strategy 1: Manual dependency updates + +1. Run `uv lock --upgrade` (or `uv lock --upgrade-package `) in your + project to refresh pinned versions in `uv.lock`. +2. Enable Dependabot if you used the `github-setup` extension (see its workflow + in cpa-templates). +3. Compare your `pyproject.toml` scripts, dependency groups, and dev tools + with the current template in + [cpa-templates](https://github.com/Create-Python-App/cpa-templates/tree/main/templates). + +Use `uv tree --outdated` when available to spot stale direct dependencies. + +## Strategy 2: Diff against a fresh scaffold + +Scaffold a new project with the same template and extensions, then diff: + +```bash +uvx create-awesome-python-app@latest my-project-new \ + -t \ + --addons \ + --no-install \ + --no-interactive + +diff -r my-project/ my-project-new/ \ + --exclude=.venv \ + --exclude=__pycache__ \ + --exclude=.git \ + --exclude=.pytest_cache \ + --exclude=.ruff_cache \ + --exclude=dist \ + --exclude=build +``` + +Review differences in config files (`pyproject.toml`, `ruff.toml`, CI +workflows, `.python-version`) and port changes selectively. + +## Strategy 3: Selective re-scaffolding + +For a single extension update: + +1. Scaffold a throwaway project with only that extension applied. +2. Copy the extension-specific files into your existing project (e.g. Alembic + migrations, auth middleware, GitHub Actions workflows). +3. Merge `pyproject.toml` dependency changes manually. + +## CNA to CPA renames + +If you are porting workflows, docs, or CI from +[create-node-app](https://github.com/Create-Node-App/create-node-app), use the +CPA equivalents: + +| CNA | CPA | +|-----|-----| +| `cna.config.json` | `cpa.config.json` | +| `package.json` manifest | `pyproject.toml` | +| `CNA_CACHE_DIR` | `CPA_CACHE_DIR` | +| `CNA_REFRESH` | `CPA_REFRESH` | +| `CNA_REFRESH_AFTER_HOURS` | `CPA_REFRESH_AFTER_HOURS` | +| `CNA_NO_CATALOG_CACHE` | `CPA_NO_CATALOG_CACHE` | +| `CNA_CATALOG_URL` | `CPA_CATALOG_URL` | +| `CNA_STRICT_VERSION` | `CPA_STRICT_VERSION` | +| `CNA_STRICT_REPRO` | `CPA_STRICT_REPRO` | +| `CNA_SKIP_GIT` | `CPA_SKIP_GIT` | +| `CNA_USER_AGENT` | `CPA_USER_AGENT` | +| `~/.cache/cna` (default cache) | `~/.cache/cpa` (default cache) | + +CLI flags are the same shape (`--template` / `-t`, `--addons`, `--cache-dir`, +`--refresh`, `--pin`, `--offline`, `--no-install`). See +[cpa-vs-cna-config.md](./cpa-vs-cna-config.md) for manifest and tooling +differences (npm vs `uv`, ESLint vs Ruff). + +## Template URL format and slug resolution + +The catalog lives in +[cpa-templates `templates.json`](https://github.com/Create-Python-App/cpa-templates/blob/main/templates.json). +Each entry has a `slug` and a `url`. + +**Slug resolution.** Pass a slug instead of a full URL and the CLI resolves it +from the catalog: + +```bash +create-awesome-python-app my-app -t fastapi-starter --addons github-setup +``` + +Run `--list-templates` or `--list-addons` to see available slugs. Invalid +slugs fail with a hint to pass a full URL. + +**GitHub URLs with `?subdir=`.** Remote templates use the monorepo layout: + +```text +https://github.com/Create-Python-App/cpa-templates?subdir=templates/fastapi-starter +https://github.com/Create-Python-App/cpa-templates?subdir=extensions/github-setup +``` + +**Local `file://` URLs.** For forks, air-gapped work, or integration tests: + +```bash +create-awesome-python-app my-app \ + -t "file:///path/to/cpa-templates?subdir=templates/fastapi-starter" \ + --no-install +``` + +**Pinning a revision.** Append `?ref=` to the URL, or use +`--pin ` (equivalent to adding `ref=` to the template URL). With +`CPA_STRICT_REPRO=1`, `ref` must be a full 40-character commit SHA. + +**Catalog override.** Point at a fork or fixture: + +```bash +export CPA_CATALOG_URL="file:///path/to/templates.json" +export CPA_NO_CATALOG_CACHE=1 # skip on-disk catalog cache +``` + +See [templates-json-schema.md](./templates-json-schema.md) for the full catalog +shape. + +## CLI version changelog + +Track releases for template and extension changes: + +- [create-python-app releases](https://github.com/Create-Python-App/create-python-app/releases) +- [cpa-templates releases](https://github.com/Create-Python-App/cpa-templates/releases) + +When upgrading the CLI: + +```bash +# ephemeral (recommended) +uvx create-awesome-python-app@latest --help + +# Homebrew / AUR / pipx installs +brew upgrade create-awesome-python-app +pipx upgrade create-awesome-python-app +``` + +Use `--strict-version` (or `CPA_STRICT_VERSION=1`) in CI to fail when the +installed CLI is not the latest PyPI release. + +Manage the template cache: + +```bash +create-awesome-python-app cache dir +create-awesome-python-app cache list +create-awesome-python-app cache update [id] +create-awesome-python-app cache clean +``` + +## Adding extensions to an existing project + +There is no `cpa add-extension` command yet. To add an extension after the fact: + +1. Browse the extension in + [cpa-templates/extensions](https://github.com/Create-Python-App/cpa-templates/tree/main/extensions). +2. Read the extension README for required files and dependencies. +3. Scaffold a minimal project with that extension and copy the relevant files. +4. Install matching dependencies from the extension's `pyproject.toml` (or run + `uv sync` in the throwaway project and mirror the dependency blocks). + +Use `--list-addons -t ` to see extensions compatible with your +base template. + +## Migrating from Cookiecutter or Copier + +If you are moving a hand-rolled Cookiecutter/Copier flow into the CPA +ecosystem: + +1. Map your template repo to a `templates.json` entry (slug, name, category, + `url` with `?subdir=`). +2. Add `cpa.config.json` at the template root (see + [cpa-config-schema.md](./cpa-config-schema.md)). +3. Prefer `uv` lockfiles (`uv.lock`) in generated projects instead of + unpinned `requirements.txt` unless the template explicitly targets pip-only + workflows. +4. Convert Jinja-style prompts to `customOptions` in `cpa.config.json` where + possible; use `--set key=value` for non-interactive runs. + +## Getting help + +- [Troubleshooting](./TROUBLESHOOTING.md) +- [GitHub Issues](https://github.com/Create-Python-App/create-python-app/issues) +- [Discussions](https://github.com/Create-Python-App/create-python-app/discussions) From 2447eaf8c86958210347e332f16b203e6890a5df Mon Sep 17 00:00:00 2001 From: ulises-jeremias Date: Thu, 16 Jul 2026 14:18:37 -0300 Subject: [PATCH 2/2] fix(docs): use even indentation in MIGRATION.md Satisfies editorconfig-checker left-padding multiples of 2. Co-authored-by: Cursor --- docs/MIGRATION.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index bb99e78..6ca4ca9 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -16,12 +16,12 @@ updates require deliberate effort. ## Strategy 1: Manual dependency updates 1. Run `uv lock --upgrade` (or `uv lock --upgrade-package `) in your - project to refresh pinned versions in `uv.lock`. + project to refresh pinned versions in `uv.lock`. 2. Enable Dependabot if you used the `github-setup` extension (see its workflow - in cpa-templates). + in cpa-templates). 3. Compare your `pyproject.toml` scripts, dependency groups, and dev tools - with the current template in - [cpa-templates](https://github.com/Create-Python-App/cpa-templates/tree/main/templates). + with the current template in + [cpa-templates](https://github.com/Create-Python-App/cpa-templates/tree/main/templates). Use `uv tree --outdated` when available to spot stale direct dependencies. @@ -55,7 +55,7 @@ For a single extension update: 1. Scaffold a throwaway project with only that extension applied. 2. Copy the extension-specific files into your existing project (e.g. Alembic - migrations, auth middleware, GitHub Actions workflows). + migrations, auth middleware, GitHub Actions workflows). 3. Merge `pyproject.toml` dependency changes manually. ## CNA to CPA renames @@ -164,11 +164,11 @@ create-awesome-python-app cache clean There is no `cpa add-extension` command yet. To add an extension after the fact: 1. Browse the extension in - [cpa-templates/extensions](https://github.com/Create-Python-App/cpa-templates/tree/main/extensions). + [cpa-templates/extensions](https://github.com/Create-Python-App/cpa-templates/tree/main/extensions). 2. Read the extension README for required files and dependencies. 3. Scaffold a minimal project with that extension and copy the relevant files. 4. Install matching dependencies from the extension's `pyproject.toml` (or run - `uv sync` in the throwaway project and mirror the dependency blocks). + `uv sync` in the throwaway project and mirror the dependency blocks). Use `--list-addons -t ` to see extensions compatible with your base template. @@ -179,14 +179,14 @@ If you are moving a hand-rolled Cookiecutter/Copier flow into the CPA ecosystem: 1. Map your template repo to a `templates.json` entry (slug, name, category, - `url` with `?subdir=`). + `url` with `?subdir=`). 2. Add `cpa.config.json` at the template root (see - [cpa-config-schema.md](./cpa-config-schema.md)). + [cpa-config-schema.md](./cpa-config-schema.md)). 3. Prefer `uv` lockfiles (`uv.lock`) in generated projects instead of - unpinned `requirements.txt` unless the template explicitly targets pip-only - workflows. + unpinned `requirements.txt` unless the template explicitly targets pip-only + workflows. 4. Convert Jinja-style prompts to `customOptions` in `cpa.config.json` where - possible; use `--set key=value` for non-interactive runs. + possible; use `--set key=value` for non-interactive runs. ## Getting help