docs: finish Package Maintenance section

Author: softwareentrepreneer

afterpython/doc/myst.yml

@@ -41,11 +41,11 @@ project:
   - title: Package Maintenance
     children:
     - file: package_maintenance/package_management.md
-    - file: package_maintenance/release_management.md
+    - file: package_maintenance/commit_workflow.md
+    - file: package_maintenance/package_releases.md
     - file: package_maintenance/ci_cd.md
   - title: References
     children:
-    - file: references/cli_commands.md
     - file: references/environment_variables.md
     - file: references/roadmap.md
   - file: CONTRIBUTING.md

afterpython/doc/package_maintenance/commit_workflow.md

@@ -0,0 +1,50 @@
+[pre-commit]: https://pre-commit.com/
+[commitizen]: https://commitizen-tools.github.io/commitizen/
+[Conventional Commits]: https://www.conventionalcommits.org
+
+
+# Commit Workflow
+
+## Pre-Commit Hooks
+Pre-commit hooks are scripts that automatically run before a commit is finalized, serving as a quality checkpoint for code changes. `afterpython` uses [pre-commit] to manage these hooks.
+
+After running `ap init`, if you agreed to create a `.pre-commit-config.yaml` file, it will be located in the `afterpython/` folder with some default hooks. Since this configuration file is not at the project root, you need to run `ap pre-commit` (or `ap pc` for short) instead of the  `pre-commit` command—it automatically uses the configuration in `afterpython/`.
+
+### Commands
+- `ap pre-commit` (or `ap pc`) — equivalent to `pre-commit --config afterpython/.pre-commit-config.yaml`
+
+
+---
+## Commitizen
+If you agreed to create a `cz.toml` file during `ap init`, `afterpython` will use [commitizen] to help you write clear, structured commit messages following the [Conventional Commits] specification.
+
+Since the `cz.toml` configuration file is located in `afterpython/` (not the project root), use `ap cz` instead of the standard `cz` command.
+
+### Writing Commit Messages
+**Recommended:** Use `ap commit` to create commits. This command:
+1. Runs pre-commit hooks on changed files to catch issues early
+2. Guides you through an interactive prompt to write a properly formatted commit message
+3. Provides flags to skip checks when needed
+
+**Alternative:** Use `git commit` directly if you're comfortable writing [Conventional Commits] format messages (e.g., `feat: add new feature`, `fix: resolve bug`). Your message must match the format enforced in `cz.toml` and pass pre-commit hook checks.
+
+
+**Bypassing checks:** To commit without running any checks:
+- `git commit --no-verify` — skip pre-commit hooks
+- `git push --no-verify` — skip pre-push hooks
+
+### Commands
+- `ap cz` (or `ap commitizen`) — equivalent to `cz --config afterpython/cz.toml`
+- `ap commit` — wrapper around `cz commit` with additional features:
+    - `ap commit --no-cz` — skip commitizen checks in pre-commit hooks
+    - `ap commit --no-pc` — skip pre-commit checks before writing the commit message
+- `git commit --no-verify` — skip all pre-commit hooks
+- `git push --no-verify` — skip all pre-push hooks
+
+
+:::{tip} Commitizen Customization
+<!-- :class: dropdown -->
+Customize the commit message format by editing `cz.toml`.
+
+See [Commitizen Customization](https://commitizen-tools.github.io/commitizen/customization/) for details.
+:::

afterpython/doc/package_maintenance/package_management.md

@@ -3,6 +3,7 @@
 [pdm]: https://github.com/pdm-project/pdm
 [ruff]: https://github.com/astral-sh/ruff
 [pixi]: https://github.com/prefix-dev/pixi
+[npm-check-updates]: https://www.npmjs.com/package/npm-check-updates
 
 # Package Management
 
@@ -32,7 +33,7 @@ As a package maintainer, you face a dilemma: your dependencies (e.g. `pandas`) r
 
 This is why minimum version updates are usually done manually—it's up to the package maintainer to decide when to require newer dependency versions.
 
-`pcu` (similar to `ncu` in Node.js) helps automate this process:
+`pcu` (similar to `ncu` ([npm-check-updates]) in Node.js) helps automate this process:
 - `pcu` shows the latest available versions of your dependencies
 - `pcu -u` updates the minimum versions in your `pyproject.toml`
 - `pcu -u --all` also updates the versions in your `.pre-commit-config.yaml`
@@ -47,5 +48,12 @@ Only update minimum versions when you have a good reason—such as needing bug f
 
 
 ---
-## pixi 🚧
-[pixi] manages both your package dependencies and your environment. For example, if your project installs `pyspark` and you need to lock Java to version 17, `pixi` handles that for you.
+## `pixi`
+[pixi] is a system-level package and environment manager that handles both Python and non-Python dependencies. For example, if your project uses `pyspark` and you need to lock Java to version 17, `pixi` can handle that for you.
+
+`afterpython` itself uses `pixi` to create a reproducible development environment.
+For instance, `afterpython` uses `gh` (the GitHub CLI), which is a non-Python dependency. Using `pixi` ensures all contributors use the exact same version of `gh` and other system tools. If you're already using `pixi` for your project, `afterpython` provides a set of commands that keep both `uv` and `pixi` synchronized:
+- `ap add <lib>` — Adds a package to both `uv` and `pixi`. Supports `--optional` and `--group` flags.
+- `ap remove <lib>` — Removes a package from both `uv` and `pixi`. Supports `--optional` and `--group` flags.
+- `ap lock` — Runs both `uv lock` and `pixi lock`
+- `ap install` — Runs `uv sync --all-extras --all-groups` and `pixi install`

afterpython/doc/package_maintenance/package_releases.md

@@ -0,0 +1,55 @@
+[commitizen]: https://commitizen-tools.github.io/commitizen/
+[SemVer]: https://semver.org
+[Python Versioning]: https://packaging.python.org/en/latest/discussions/versioning/
+[PyPI]: https://pypi.org/
+
+
+# Package Releases
+
+## Version Bumping
+`ap bump` automatically increments your project version using [commitizen]'s `cz bump` under the hood.
+
+### Commands
+- `ap bump` — automatically bump version based on conventional commits
+- `ap bump --pre` — bump to a pre-release version (e.g., `0.1.0.dev3` → `0.1.0.rc0`)
+- `ap bump --release` — bump to a release version (e.g., `0.1.0.rc0` → `0.1.0`)
+    - **NOTE**: This command will **automatically trigger** the [release](./package_releases.md#releasing-your-package) workflow, you don't need to run `ap release` manually.
+
+:::{seealso} Versioning
+:class: dropdown
+See [SemVer] and [Python Versioning] to learn more about versioning in Python packages.
+:::
+
+---
+## PyPI and GitHub Releases
+If you agreed to create `cz.toml` during `ap init`, `afterpython` automatically creates a GitHub Actions workflow (`.github/workflows/release.yml`) that publishes your package to [PyPI] and creates GitHub releases.
+
+### PyPI Setup
+To enable trusted publishing on PyPI:
+
+1. Go to [PyPI] and navigate to your project
+2. Click **Manage** → **Publishing** (left sidebar)
+3. Under the **GitHub** tab, fill in:
+   - **Owner:** Your GitHub username or organization name
+   - **Repository:** Your repository name
+   - **Workflow name:** `release.yml`
+
+:::{note} Using an API Token
+:class: dropdown
+To use an API token instead (e.g., `UV_PUBLISH_TOKEN`), you'll need to modify the `release.yml` workflow file.
+:::
+
+### Releasing Your Package
+`ap release` manually pushes the git tag created by `ap bump` to GitHub, which triggers the `release.yml` workflow. This command is unnecessary if you've already successfully run `ap bump --release`.
+
+**Commands:**
+- `ap release` — release the current version to PyPI and GitHub
+- `ap release --force` — force release even for development versions
+
+
+---
+## Semantic Release 🚧
+
+
+---
+## Changlog 🚧

afterpython/doc/package_maintenance/release_management.md

@@ -13,7 +13,7 @@
 )
 @click.pass_context
 def check(ctx):
-    """Simple wrapper for ruff check for convenience, always use the afterpython/ruff.toml if it exists"""
+    """Run ruff linter (uses afterpython/ruff.toml if available)"""
     from afterpython.utils import handle_passthrough_help
 
     # Show both our options and ruff's help and exit

afterpython/doc/references/cli_commands.md

@@ -26,10 +26,10 @@
 @click.option(
     "--all",
     is_flag=True,
-    help='--all passed to "myst clean", also clean afterpython build directories (_build/ and _website/build/)',
+    help="Also clean AfterPython build directories (_build/ and _website/build/)",
 )
 def clean(ctx, all: bool):
-    """Clean the build directory"""
+    """Clean build artifacts from content types and website"""
     from afterpython.utils import handle_passthrough_help
 
     # Show both our options and myst's help and exit

src/afterpython/cli/commands/check.py

@@ -13,7 +13,10 @@
 )
 @click.pass_context
 @click.option(
-    "--no-cz", "--no-commitizen", is_flag=True, help="Skip running 'cz commit'"
+    "--no-cz",
+    "--no-commitizen",
+    is_flag=True,
+    help="Skip 'commitizen' and 'commitizen-branch' pre-commit hooks",
 )
 @click.option(
     "--no-pc",
@@ -22,7 +25,7 @@
     help="Skip running pre-commit checks before commit",
 )
 def commit(ctx, no_cz: bool, no_pc: bool):
-    """Run 'cz commit'"""
+    """Create a conventional commit with interactive prompts"""
     from afterpython.utils import handle_passthrough_help
 
     # Show both our options and commitizen's help and exit

src/afterpython/cli/commands/clean.py

@@ -13,7 +13,7 @@
 )
 @click.pass_context
 def commitizen(ctx):
-    """Run commitizen"""
+    """Run commitizen CLI (uses afterpython/cz.toml)"""
     from afterpython.utils import handle_passthrough_help
 
     # Show both our options and commitizen's help and exit