Skip to content

AGENTS.md

Latest commit

 

History

History
91 lines (70 loc) · 3.9 KB

AGENTS.md

File metadata and controls

91 lines (70 loc) · 3.9 KB
Raw

Agents

Overview

canonical/craft-store is a Python library for interacting with Canonical storefront APIs, such as those of the Snap Store or Charmhub.

Craft apps and libraries

Craft Store 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-store in conjunction with the following craft libraries:

Package Role
craft-application Application framework: CLI lifecycle, configuration, service management, remote build support
craft-archives Repository and package archive management (apt sources, keyrings)
craft-cli Terminal output, progress reporting, error formatting
craft-grammar Architecture and platform-conditional YAML in project files
craft-parts Part lifecycle (pull, build, overlay, stage, prime) steps, plugins
craft-platforms Platform and architecture abstractions
craft-providers Build environment manager for LXD and Multipass

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

Development

Craft Store 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.