craft-platforms

Imported from canonical/craft-platforms (AGENTS.md). Install upstream with npx skills add canonical/craft-platforms. Copyright stays with the author.

Agents

Overview

canonical/craft-platforms is a Python library that handles platform information for Snapcraft, Charmcraft, Rockcraft, and other craft apps. A platform is the combination of an operating system version and its target architecture. The library parses platform information in a craft project file (e.g. snapcraft.yaml) and creates a build plan manifest describing the environments where the artifact can build and run.

Craft apps and libraries

craft-platforms is used by craft apps, including but not limited to Charmcraft, Debcraft, Imagecraft, Rockcraft, and Snapcraft. The source code for these apps is at https://github.com/canonical/.

Craft apps use craft-platforms in conjunction with the following craft libraries:

The source code for these libraries is at https://github.com/canonical/.

Development

craft-platforms uses uv for dependency management.

make setup          # Install all deps

Running tests

make test           # Full test suite
make test-fast      # Fast tests only
uv run pytest tests/unit/path/to/test_file.py::test_name  # run a specific test

Formatting and linting

make format
make lint

Documentation

Documentation uses the Diátaxis framework and the Sphinx Stack. All documentation must follow the Starcraft style guide and the overall Canonical style guide.

make setup-docs
make docs
make lint-docs

Practices

• Backward compatibility is a hard requirement. Apps using this library must continue to build successfully without requiring user modifications. Changes that alter behavior, configuration, APIs, defaults, or validation rules must be opt-in. When modifying business logic, verify that existing behavior is preserved and explain how you verified it.
• Make the smallest safe change necessary to resolve the issue. Avoid unrelated bug fixes, opportunistic cleanup, and refactoring unless required. The right amount of complexity is the minimum needed for the current task.
• Never speculate about code you haven't inspected.
• Follow the project's existing conventions regarding style, docstrings, logging, comments, and testing.
• Comments should explain complex business logic, non-obvious algorithms, regex, and other "gotchas". Comments should be brief, explain "why" not "how", and be helpful for future maintainers.
• Update relevant documentation and release notes to reflect code changes.

Processes

• If you're contributing to a specific release, target the upstream hotfix/<major.minor> branch, if it exists. Otherwise, target the main branch.
• Commit headers are no more than 80 characters, follow Conventional Commits, and use the following types:
  • ci, build, feat, fix, perf, refactor, style, test, docs, chore
• Always run make format, make lint, and make test-fast before completing your work.