From 919154d89df4bc91b0c9c2500babfe5adebda213 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 5 Nov 2025 15:12:52 +0000 Subject: [PATCH 1/8] Initial plan From d96b8648a24a925d4a7921a74ec4e90af34c421f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 5 Nov 2025 16:02:27 +0000 Subject: [PATCH 2/8] docs: add agents.md guide for AI coding assistants --- agents.md | 318 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 318 insertions(+) create mode 100644 agents.md diff --git a/agents.md b/agents.md new file mode 100644 index 000000000..3765feff7 --- /dev/null +++ b/agents.md @@ -0,0 +1,318 @@ +# Agents Guide + +This guide helps AI coding agents and automation tools work effectively with the craft-application repository. + +## Overview + +**craft-application** is a Python library that serves as the base framework for all Starcraft applications (like snapcraft, charmcraft, etc.). It provides common mechanisms for application services, project models, and other shared functionality. + +- **Language**: Python 3.10+ +- **License**: LGPL-3.0 +- **Build System**: setuptools with setuptools_scm +- **Package Manager**: uv +- **Documentation**: See [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTING.md) + +## Development Workflow + +### Initial Setup + +1. **Clone the repository** (see [CONTRIBUTING.md](CONTRIBUTING.md) for details): + + ```bash + git clone https://github.com/canonical/craft-application --recurse-submodules + cd craft-application + ``` + +2. **Set up the development environment**: + + ```bash + make setup + ``` + + This installs all dependencies, sets up the virtual environment, and configures pre-commit hooks. + +3. **Verify the setup**: + ```bash + make lint + make test + ``` + +### Common Development Tasks + +Use these `make` targets for everyday development. Run `make help` to see all available targets. + +#### Formatting Code + +```bash +make format # Run all automatic formatters +make format-ruff # Format with ruff only +make format-codespell # Fix spelling issues +make format-prettier # Format YAML/JSON/Markdown files +``` + +#### Linting Code + +```bash +make lint # Run all linters +make lint-ruff # Lint with ruff +make lint-mypy # Type check with mypy +make lint-pyright # Type check with pyright +make lint-codespell # Check spelling +make lint-docs # Lint documentation +make lint-prettier # Check YAML/JSON/Markdown formatting +make lint-shellcheck # Lint shell scripts +``` + +#### Running Tests + +```bash +make test # Run all tests +make test-fast # Run fast tests only (excludes tests marked as 'slow') +make test-slow # Run slow tests only +make test-coverage # Generate coverage report +``` + +#### Building Documentation + +```bash +make docs # Build documentation +make docs-auto # Build and auto-reload docs at localhost:8080 +``` + +#### Cleaning Up + +```bash +make clean # Remove build artifacts and temporary files +``` + +### Pre-commit Hooks + +This project uses pre-commit hooks that run automatically on `git commit`. They include: + +- Ruff linting and formatting +- Prettier formatting for YAML/JSON/Markdown +- Trailing whitespace removal +- End-of-file fixer +- Various file checks + +See [.pre-commit-config.yaml](.pre-commit-config.yaml) for the full configuration. + +### Commit Message Format + +Follow [Conventional Commits](https://www.conventionalcommits.org/) style: + +``` +: + +[optional body] + +[optional footer] +``` + +Common types (in priority order): + +- `ci`: CI/CD changes +- `build`: Build system changes +- `feat`: New features +- `fix`: Bug fixes +- `perf`: Performance improvements +- `refactor`: Code refactoring +- `style`: Code style changes +- `test`: Test changes +- `docs`: Documentation changes +- `chore`: Maintenance tasks + +See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on commit conventions. + +## Project Structure + +``` +craft_application/ +├── commands/ # CLI command implementations +├── git/ # Git integration utilities +├── launchpad/ # Launchpad integration for remote builds +├── misc/ # Miscellaneous utilities +├── models/ # Pydantic data models +├── remote/ # Remote build support +├── services/ # Application services (lifecycle, package, etc.) +├── util/ # General utility functions +├── application.py # Main Application class +├── errors.py # Custom exceptions +└── fetch.py # File fetching utilities + +tests/ +├── unit/ # Unit tests (mirror craft_application structure) +├── integration/ # Integration tests +├── spread/ # Spread system tests +└── data/ # Test data and fixtures +``` + +## Testing Guidelines + +### Test Organization + +- **Unit tests**: In `tests/unit/` - mirror the structure of `craft_application/` +- **Integration tests**: In `tests/integration/` - test component interactions +- **Spread tests**: In `tests/spread/` - system-level tests using the Spread framework + +### Writing Tests + +- Use pytest for unit and integration tests +- Follow existing test patterns in the repository +- Add tests for all non-trivial code changes +- Mark slow tests with `@pytest.mark.slow` decorator +- Use fixtures and mocks appropriately + +### Running Specific Tests + +```bash +# Run tests in a specific file +uv run pytest tests/unit/test_application.py + +# Run tests matching a pattern +uv run pytest -k "test_pattern" + +# Run with verbose output +uv run pytest -v + +# Run in parallel (if pytest-xdist is available) +uv run pytest -n auto +``` + +## Code Quality Standards + +### Type Checking + +- All code in `craft_application/` must be fully type-annotated +- Uses both mypy and pyright for type checking +- Configuration in `pyproject.toml` under `[tool.mypy]` and `[tool.pyright]` + +### Linting + +- **Ruff**: Primary linter and formatter (replaces flake8, black, isort) + - Line length: 88 characters + - Target: Python 3.10+ + - Configuration in `pyproject.toml` under `[tool.ruff]` +- **Codespell**: Spell checking +- **Prettier**: For YAML, JSON, and Markdown files + +### Code Style + +- Follow PEP 8 conventions +- Use type hints for all function parameters and return values +- Add docstrings for public APIs (Google/NumPy style) +- Keep functions focused and testable +- Prefer composition over inheritance + +## Dependencies + +### Adding Dependencies + +1. Add the dependency to `pyproject.toml` under `[project.dependencies]` +2. For development-only dependencies, add to `[dependency-groups]` +3. Update the lock file: `uv lock` +4. Test that it works: `make setup && make test` + +### Dependency Groups + +- `dev`: Core development dependencies (pytest, coverage, etc.) +- `lint`: Linting tools +- `types`: Type checking tools (mypy, type stubs) +- `docs`: Documentation tools (Sphinx, etc.) +- `remote`: Optional remote-build support (launchpadlib) +- `apt`: Optional python-apt support + +## Common Patterns + +### Working with Services + +Services in `craft_application/services/` follow a consistent pattern: + +- Inherit from appropriate base classes +- Use dependency injection +- Implement well-defined interfaces +- Are tested in isolation with mocks + +### Working with Models + +Pydantic models in `craft_application/models/`: + +- Use Pydantic v2 syntax +- Include validators where appropriate +- Provide clear docstrings +- Support serialization/deserialization + +### Error Handling + +Custom exceptions in `craft_application/errors.py`: + +- Inherit from `CraftError` or appropriate subclass +- Include clear error messages +- Provide context for debugging + +## Continuous Integration + +GitHub Actions workflows are in `.github/workflows/`: + +- `qa.yaml`: Main quality assurance (lint, type check, test) +- `spread.yaml`: Spread integration tests +- `tics.yaml`: TICS quality analysis +- `policy.yaml`: Security and policy checks +- `release-publish.yaml`: Release automation + +## Documentation + +### Building Docs + +```bash +make docs # Build static documentation +make docs-auto # Build with live reload +make lint-docs # Check documentation quality +``` + +### Documentation Structure + +- Source: `docs/` directory +- Common docs: `docs/common/` (shared with downstream apps) +- Built docs: `docs/_build/` (gitignored) +- Uses Sphinx with canonical-sphinx theme +- Follows Diátaxis framework (tutorials, how-to, reference, explanation) + +## Tips for Agents + +1. **Always run setup first**: `make setup` ensures a clean development environment +2. **Test incrementally**: Run `make test-fast` during development, `make test` before committing +3. **Format before committing**: `make format` or rely on pre-commit hooks +4. **Check types early**: Run `make lint-mypy lint-pyright` to catch type errors +5. **Reference existing code**: Look at similar implementations for patterns and style +6. **Read CONTRIBUTING.md**: Contains detailed guidelines for contributors +7. **Use uv commands directly**: For fine-grained control, use `uv run ` +8. **Clean when stuck**: `make clean && rm -rf .venv && make setup` for a fresh start + +## Important Notes + +- **Minimal changes**: Make the smallest possible changes to achieve the goal +- **Don't remove working code**: Unless fixing a bug or security issue in changed code +- **Update docs**: If changing public APIs or adding features +- **Test all changes**: Don't skip tests even for "simple" changes +- **Follow conventions**: Match the style and patterns of existing code +- **Version pinning**: Be cautious with dependency versions (see pygit2 comments in pyproject.toml) + +## Getting Help + +- **Documentation**: https://canonical-craft-application.readthedocs-hosted.com/ +- **Issues**: https://github.com/canonical/craft-application/issues +- **Matrix Chat**: #starcraft-development:ubuntu.com +- **Code of Conduct**: https://ubuntu.com/community/ethos/code-of-conduct + +## Future Considerations + +_Note: The maintainer (@lengau) requested to tackle specific pain points and constraints later. This section is a placeholder for that future documentation._ + +Areas to document: + +- Common pitfalls when working with craft-application +- Breaking change patterns to avoid +- Complex dependency constraints +- Platform-specific considerations +- Performance optimization guidelines From 20c1cfe91aff808db2f3038f9c07bf02f71b34a4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 6 Nov 2025 10:55:46 +0000 Subject: [PATCH 3/8] docs: streamline agents.md based on review feedback Co-authored-by: lengau <4305943+lengau@users.noreply.github.com> --- agents.md | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/agents.md b/agents.md index 3765feff7..1b7625800 100644 --- a/agents.md +++ b/agents.md @@ -45,38 +45,43 @@ Use these `make` targets for everyday development. Run `make help` to see all av ```bash make format # Run all automatic formatters -make format-ruff # Format with ruff only -make format-codespell # Fix spelling issues -make format-prettier # Format YAML/JSON/Markdown files ``` #### Linting Code ```bash make lint # Run all linters -make lint-ruff # Lint with ruff -make lint-mypy # Type check with mypy -make lint-pyright # Type check with pyright -make lint-codespell # Check spelling -make lint-docs # Lint documentation -make lint-prettier # Check YAML/JSON/Markdown formatting -make lint-shellcheck # Lint shell scripts ``` #### Running Tests ```bash make test # Run all tests -make test-fast # Run fast tests only (excludes tests marked as 'slow') -make test-slow # Run slow tests only -make test-coverage # Generate coverage report +``` + +To run tests directly within the uv-created virtual environment (useful when only modifying tests): + +```bash +# Activate the virtual environment (if not already activated) +source .venv/bin/activate + +# Run tests in a specific file +pytest tests/unit/test_application.py + +# Run tests matching a pattern +pytest -k "test_pattern" + +# Run with verbose output +pytest -v + +# Run in parallel (if pytest-xdist is available) +pytest -n auto ``` #### Building Documentation ```bash make docs # Build documentation -make docs-auto # Build and auto-reload docs at localhost:8080 ``` #### Cleaning Up @@ -266,14 +271,12 @@ GitHub Actions workflows are in `.github/workflows/`: ```bash make docs # Build static documentation -make docs-auto # Build with live reload -make lint-docs # Check documentation quality ``` ### Documentation Structure - Source: `docs/` directory -- Common docs: `docs/common/` (shared with downstream apps) +- Common docs: `docs/common/` - Contains app-agnostic documentation that can be integrated into downstream craft tools (snapcraft, charmcraft, etc.). Write documentation here when documenting features inherited by downstream applications. - Built docs: `docs/_build/` (gitignored) - Uses Sphinx with canonical-sphinx theme - Follows Diátaxis framework (tutorials, how-to, reference, explanation) @@ -281,9 +284,9 @@ make lint-docs # Check documentation quality ## Tips for Agents 1. **Always run setup first**: `make setup` ensures a clean development environment -2. **Test incrementally**: Run `make test-fast` during development, `make test` before committing +2. **Test incrementally**: Run `make test` to validate changes 3. **Format before committing**: `make format` or rely on pre-commit hooks -4. **Check types early**: Run `make lint-mypy lint-pyright` to catch type errors +4. **Check types early**: Run `make lint` to catch type errors and other issues 5. **Reference existing code**: Look at similar implementations for patterns and style 6. **Read CONTRIBUTING.md**: Contains detailed guidelines for contributors 7. **Use uv commands directly**: For fine-grained control, use `uv run ` @@ -302,8 +305,6 @@ make lint-docs # Check documentation quality - **Documentation**: https://canonical-craft-application.readthedocs-hosted.com/ - **Issues**: https://github.com/canonical/craft-application/issues -- **Matrix Chat**: #starcraft-development:ubuntu.com -- **Code of Conduct**: https://ubuntu.com/community/ethos/code-of-conduct ## Future Considerations From dba07746f345bf346e3c3b4b6c4b511e050526e9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 6 Nov 2025 11:26:32 +0000 Subject: [PATCH 4/8] docs: refine agents.md based on detailed review feedback Co-authored-by: lengau <4305943+lengau@users.noreply.github.com> --- agents.md | 121 ++++++++++++++++++------------------------------------ 1 file changed, 39 insertions(+), 82 deletions(-) diff --git a/agents.md b/agents.md index 1b7625800..aebca63fd 100644 --- a/agents.md +++ b/agents.md @@ -59,23 +59,14 @@ make lint # Run all linters make test # Run all tests ``` -To run tests directly within the uv-created virtual environment (useful when only modifying tests): +To run specific tests directly (useful when only modifying tests): ```bash -# Activate the virtual environment (if not already activated) -source .venv/bin/activate - # Run tests in a specific file -pytest tests/unit/test_application.py +uv run pytest tests/unit/test_application.py # Run tests matching a pattern -pytest -k "test_pattern" - -# Run with verbose output -pytest -v - -# Run in parallel (if pytest-xdist is available) -pytest -n auto +uv run pytest -k "test_pattern" ``` #### Building Documentation @@ -92,15 +83,7 @@ make clean # Remove build artifacts and temporary files ### Pre-commit Hooks -This project uses pre-commit hooks that run automatically on `git commit`. They include: - -- Ruff linting and formatting -- Prettier formatting for YAML/JSON/Markdown -- Trailing whitespace removal -- End-of-file fixer -- Various file checks - -See [.pre-commit-config.yaml](.pre-commit-config.yaml) for the full configuration. +This project uses pre-commit hooks that run automatically on `git commit`. The `make setup` command installs these hooks. Always ensure the pre-commit hooks are installed and run before committing. See [.pre-commit-config.yaml](.pre-commit-config.yaml) for the full configuration. ### Commit Message Format @@ -131,26 +114,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on commit conventions. ## Project Structure -``` -craft_application/ -├── commands/ # CLI command implementations -├── git/ # Git integration utilities -├── launchpad/ # Launchpad integration for remote builds -├── misc/ # Miscellaneous utilities -├── models/ # Pydantic data models -├── remote/ # Remote build support -├── services/ # Application services (lifecycle, package, etc.) -├── util/ # General utility functions -├── application.py # Main Application class -├── errors.py # Custom exceptions -└── fetch.py # File fetching utilities - -tests/ -├── unit/ # Unit tests (mirror craft_application structure) -├── integration/ # Integration tests -├── spread/ # Spread system tests -└── data/ # Test data and fixtures -``` +See the repository's directory structure for details. Key directories: + +- `craft_application/` - Main library code +- `tests/unit/` - Unit tests (mirror `craft_application/` structure) +- `tests/integration/` - Integration tests +- `tests/spread/` - Spread system tests +- `docs/` - Documentation source ## Testing Guidelines @@ -158,7 +128,12 @@ tests/ - **Unit tests**: In `tests/unit/` - mirror the structure of `craft_application/` - **Integration tests**: In `tests/integration/` - test component interactions -- **Spread tests**: In `tests/spread/` - system-level tests using the Spread framework +- **Spread tests**: In `tests/spread/` - system-level tests using the [Spread framework](https://github.com/canonical/spread) + - Install spread: `snap install spread` + - Run spread tests: `spread` (from repository root) + - Spread tests are defined in `task.yaml` files within test directories + - Each test has `prepare`, `execute`, and optionally `restore` sections + - Configuration in `spread.yaml` at repository root ### Writing Tests @@ -167,39 +142,17 @@ tests/ - Add tests for all non-trivial code changes - Mark slow tests with `@pytest.mark.slow` decorator - Use fixtures and mocks appropriately - -### Running Specific Tests - -```bash -# Run tests in a specific file -uv run pytest tests/unit/test_application.py - -# Run tests matching a pattern -uv run pytest -k "test_pattern" - -# Run with verbose output -uv run pytest -v - -# Run in parallel (if pytest-xdist is available) -uv run pytest -n auto -``` +- Aim for complete line and branch coverage where feasible ## Code Quality Standards -### Type Checking +### Type Checking and Linting -- All code in `craft_application/` must be fully type-annotated -- Uses both mypy and pyright for type checking -- Configuration in `pyproject.toml` under `[tool.mypy]` and `[tool.pyright]` +All configuration is in `pyproject.toml`. See that file for details on: -### Linting - -- **Ruff**: Primary linter and formatter (replaces flake8, black, isort) - - Line length: 88 characters - - Target: Python 3.10+ - - Configuration in `pyproject.toml` under `[tool.ruff]` -- **Codespell**: Spell checking -- **Prettier**: For YAML, JSON, and Markdown files +- Type checking (mypy, pyright) +- Linting (ruff, codespell) +- Code formatting standards ### Code Style @@ -215,17 +168,19 @@ uv run pytest -n auto 1. Add the dependency to `pyproject.toml` under `[project.dependencies]` 2. For development-only dependencies, add to `[dependency-groups]` -3. Update the lock file: `uv lock` -4. Test that it works: `make setup && make test` +3. Run: `uv lock && uv sync` +4. Test that it works: `make test` ### Dependency Groups +See `pyproject.toml` under `[dependency-groups]` for the complete list. Key groups include: + - `dev`: Core development dependencies (pytest, coverage, etc.) - `lint`: Linting tools - `types`: Type checking tools (mypy, type stubs) - `docs`: Documentation tools (Sphinx, etc.) - `remote`: Optional remote-build support (launchpadlib) -- `apt`: Optional python-apt support +- `apt`: Optional python-apt support (required on Linux but not included in dev group due to platform-specific versioning; use appropriate `dev-{codename}` group) ## Common Patterns @@ -252,8 +207,9 @@ Pydantic models in `craft_application/models/`: Custom exceptions in `craft_application/errors.py`: - Inherit from `CraftError` or appropriate subclass -- Include clear error messages -- Provide context for debugging +- Include error message templates in the class definition +- Store specific values as instance attributes +- Only require callers to pass specific values, not full messages ## Continuous Integration @@ -276,7 +232,7 @@ make docs # Build static documentation ### Documentation Structure - Source: `docs/` directory -- Common docs: `docs/common/` - Contains app-agnostic documentation that can be integrated into downstream craft tools (snapcraft, charmcraft, etc.). Write documentation here when documenting features inherited by downstream applications. +- Common docs: `docs/common/` - Contains app-agnostic documentation that can be integrated into downstream craft tools (snapcraft, charmcraft, etc.). Write documentation here when documenting features inherited by downstream applications. Documentation from `docs/common/` should be included from the main `docs/` directory either by linking in a table of contents or using the Sphinx include directive. - Built docs: `docs/_build/` (gitignored) - Uses Sphinx with canonical-sphinx theme - Follows Diátaxis framework (tutorials, how-to, reference, explanation) @@ -285,12 +241,13 @@ make docs # Build static documentation 1. **Always run setup first**: `make setup` ensures a clean development environment 2. **Test incrementally**: Run `make test` to validate changes -3. **Format before committing**: `make format` or rely on pre-commit hooks -4. **Check types early**: Run `make lint` to catch type errors and other issues -5. **Reference existing code**: Look at similar implementations for patterns and style -6. **Read CONTRIBUTING.md**: Contains detailed guidelines for contributors -7. **Use uv commands directly**: For fine-grained control, use `uv run ` -8. **Clean when stuck**: `make clean && rm -rf .venv && make setup` for a fresh start +3. **Run spread tests locally**: Run `spread` before committing to catch system-level issues +4. **Format before committing**: `make format` or rely on pre-commit hooks +5. **Check types early**: Run `make lint` to catch type errors and other issues +6. **Reference existing code**: Look at similar implementations for patterns and style +7. **Read CONTRIBUTING.md**: Contains detailed guidelines for contributors +8. **Use uv commands directly**: For fine-grained control, use `uv run ` +9. **Clean when stuck**: `make clean && rm -rf .venv && make setup` for a fresh start ## Important Notes From 8d415ba2c759f07f137df8c604a55b06384e386a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 6 Nov 2025 14:04:57 +0000 Subject: [PATCH 5/8] docs: enhance agents.md with scopes, uv add, validation, spread backend, and breaking changes Co-authored-by: lengau <4305943+lengau@users.noreply.github.com> --- agents.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 70 insertions(+), 10 deletions(-) diff --git a/agents.md b/agents.md index aebca63fd..f9414ed99 100644 --- a/agents.md +++ b/agents.md @@ -87,16 +87,24 @@ This project uses pre-commit hooks that run automatically on `git commit`. The ` ### Commit Message Format -Follow [Conventional Commits](https://www.conventionalcommits.org/) style: +Follow [Conventional Commits](https://www.conventionalcommits.org/) style with a scope: ``` -: +(): [optional body] [optional footer] ``` +The scope should indicate the component or area affected (e.g., `TestService`, `commands`, `launchpad`, `models`). Use of a scope is strongly encouraged. + +Examples: + +- `feat(TestService): add new validation method` +- `feat(commands): add --verbose flag to pack command` +- `fix(launchpad): resolve authentication timeout issue` + Common types (in priority order): - `ci`: CI/CD changes @@ -166,10 +174,20 @@ All configuration is in `pyproject.toml`. See that file for details on: ### Adding Dependencies -1. Add the dependency to `pyproject.toml` under `[project.dependencies]` -2. For development-only dependencies, add to `[dependency-groups]` -3. Run: `uv lock && uv sync` -4. Test that it works: `make test` +Use the `uv add` command to add dependencies: + +```bash +# Add a runtime dependency +uv add + +# Add a development dependency +uv add --group dev + +# Add to a specific group +uv add --group lint +``` + +After adding dependencies, test that everything works: `make test` ### Dependency Groups @@ -198,6 +216,10 @@ Services in `craft_application/services/` follow a consistent pattern: Pydantic models in `craft_application/models/`: - Use Pydantic v2 syntax +- Prefer declarative validation where possible +- If declarative validation would result in a bad error message, include a `@field_validator` with mode `before` that provides a better error message +- When using validator functions/methods, also include the validation in extra JSON schema structures where possible +- Document validation rules in plain English in docstrings - Include validators where appropriate - Provide clear docstrings - Support serialization/deserialization @@ -241,7 +263,10 @@ make docs # Build static documentation 1. **Always run setup first**: `make setup` ensures a clean development environment 2. **Test incrementally**: Run `make test` to validate changes -3. **Run spread tests locally**: Run `spread` before committing to catch system-level issues +3. **Run spread tests locally**: Before committing, run spread tests using the LXD backend (if available). The default Google backend requires cloud credentials. To use LXD: + - Ensure LXD is installed: `snap install lxd` + - Initialize LXD if needed: `sudo lxd init --minimal` + - Run spread with LXD: `spread lxd:` (note the trailing colon) 4. **Format before committing**: `make format` or rely on pre-commit hooks 5. **Check types early**: Run `make lint` to catch type errors and other issues 6. **Reference existing code**: Look at similar implementations for patterns and style @@ -265,12 +290,47 @@ make docs # Build static documentation ## Future Considerations -_Note: The maintainer (@lengau) requested to tackle specific pain points and constraints later. This section is a placeholder for that future documentation._ +### Breaking Change Patterns to Avoid + +Based on the project's history (see `docs/reference/changelog.rst` for details), avoid these common breaking change patterns: + +**Dependencies** + +- Changing dependency version constraints too broadly (e.g., pygit2 constraints affecting snap packages) +- Making optional dependencies mandatory + +**Models** + +- Making optional fields mandatory without proper adoption fields support +- Reserving platform names without migration path (e.g., `any`, `*`) +- Adding character restrictions to existing string fields (e.g., `/` in platform names) +- Changing error message formats or structures for Pydantic models + +**APIs** + +- Changing function signatures (especially parameter types like `ErrorDetails` vs `ErrorDict`) +- Modifying exception handling behavior (e.g., catching `BaseException` vs `Exception`) +- Changing default behaviors that affect downstream apps + +**Services** + +- Modifying environment variables set by services +- Changing compatibility tags that affect instance reuse +- Altering how project variables are managed + +When making changes: + +1. Check if the change breaks existing APIs or behaviors +2. Consider adding deprecation warnings before removal +3. Provide migration paths in documentation +4. Update the changelog with clear "Breaking changes" sections +5. Consider semantic versioning implications + +_Note: The maintainer (@lengau) requested to document specific pain points and constraints. This section will be expanded with more operational details._ -Areas to document: +Areas still to document: - Common pitfalls when working with craft-application -- Breaking change patterns to avoid - Complex dependency constraints - Platform-specific considerations - Performance optimization guidelines From 772748e24841840301ac444242775128cc1e2629 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 6 Nov 2025 14:16:25 +0000 Subject: [PATCH 6/8] docs(agents): clarify prerequisites, setup requirements, and spread test usage Co-authored-by: lengau <4305943+lengau@users.noreply.github.com> --- agents.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/agents.md b/agents.md index f9414ed99..6cc8de0ab 100644 --- a/agents.md +++ b/agents.md @@ -14,6 +14,14 @@ This guide helps AI coding agents and automation tools work effectively with the ## Development Workflow +### Prerequisites + +Before starting development, ensure you have: + +- Python 3.10 or later +- Git +- `uv` package manager (will be automatically installed by `make setup` if not present, or install manually via `sudo snap install --classic astral-uv`) + ### Initial Setup 1. **Clone the repository** (see [CONTRIBUTING.md](CONTRIBUTING.md) for details): @@ -32,11 +40,14 @@ This guide helps AI coding agents and automation tools work effectively with the This installs all dependencies, sets up the virtual environment, and configures pre-commit hooks. 3. **Verify the setup**: + ```bash make lint make test ``` + Note: If `make test` fails due to network issues (common in restricted environments), focus on running specific tests relevant to your changes using `uv run pytest`. + ### Common Development Tasks Use these `make` targets for everyday development. Run `make help` to see all available targets. @@ -59,7 +70,7 @@ make lint # Run all linters make test # Run all tests ``` -To run specific tests directly (useful when only modifying tests): +To run specific tests directly (requires `make setup` to be run first): ```bash # Run tests in a specific file @@ -97,7 +108,7 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/) style with a [optional footer] ``` -The scope should indicate the component or area affected (e.g., `TestService`, `commands`, `launchpad`, `models`). Use of a scope is strongly encouraged. +The scope should indicate the component or area affected (e.g., `TestService`, `commands`, `launchpad`, `models`). Use of a scope is strongly encouraged. Choose a scope that represents the primary component or module being changed. If multiple components are affected significantly, consider breaking into multiple commits. Examples: @@ -137,7 +148,7 @@ See the repository's directory structure for details. Key directories: - **Unit tests**: In `tests/unit/` - mirror the structure of `craft_application/` - **Integration tests**: In `tests/integration/` - test component interactions - **Spread tests**: In `tests/spread/` - system-level tests using the [Spread framework](https://github.com/canonical/spread) - - Install spread: `snap install spread` + - Install spread: `sudo snap install spread` (optional - typically run in CI, not required for regular development) - Run spread tests: `spread` (from repository root) - Spread tests are defined in `task.yaml` files within test directories - Each test has `prepare`, `execute`, and optionally `restore` sections @@ -156,7 +167,7 @@ See the repository's directory structure for details. Key directories: ### Type Checking and Linting -All configuration is in `pyproject.toml`. See that file for details on: +All configuration is in `pyproject.toml`. See `[tool.mypy]`, `[tool.pyright]`, `[tool.ruff]`, and `[tool.codespell]` sections for details on: - Type checking (mypy, pyright) - Linting (ruff, codespell) @@ -187,7 +198,7 @@ uv add --group dev uv add --group lint ``` -After adding dependencies, test that everything works: `make test` +Note: `uv add` automatically updates `uv.lock` and syncs the environment. After adding dependencies, test that everything works: `make test` ### Dependency Groups @@ -263,10 +274,11 @@ make docs # Build static documentation 1. **Always run setup first**: `make setup` ensures a clean development environment 2. **Test incrementally**: Run `make test` to validate changes -3. **Run spread tests locally**: Before committing, run spread tests using the LXD backend (if available). The default Google backend requires cloud credentials. To use LXD: - - Ensure LXD is installed: `snap install lxd` +3. **Run spread tests locally**: Before committing, run spread tests using the LXD backend (if available and if making system-level changes). The default Google backend requires cloud credentials. To use LXD: + - Ensure LXD is installed: `sudo snap install lxd` - Initialize LXD if needed: `sudo lxd init --minimal` - - Run spread with LXD: `spread lxd:` (note the trailing colon) + - Run spread with LXD: `spread lxd:` (the trailing colon runs all LXD-configured systems from spread.yaml) + - Note: LXD setup requires root/sudo access and may not work in all environments. Spread tests are optional for most development and will run in CI. 4. **Format before committing**: `make format` or rely on pre-commit hooks 5. **Check types early**: Run `make lint` to catch type errors and other issues 6. **Reference existing code**: Look at similar implementations for patterns and style From 7f7f1f809b3d33d1f2d62250a06fbbd5c6f2275a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 6 Nov 2025 14:21:38 +0000 Subject: [PATCH 7/8] docs(agents): use official Go installation method for spread Co-authored-by: lengau <4305943+lengau@users.noreply.github.com> --- agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agents.md b/agents.md index 6cc8de0ab..0fb048b2b 100644 --- a/agents.md +++ b/agents.md @@ -148,7 +148,7 @@ See the repository's directory structure for details. Key directories: - **Unit tests**: In `tests/unit/` - mirror the structure of `craft_application/` - **Integration tests**: In `tests/integration/` - test component interactions - **Spread tests**: In `tests/spread/` - system-level tests using the [Spread framework](https://github.com/canonical/spread) - - Install spread: `sudo snap install spread` (optional - typically run in CI, not required for regular development) + - Install spread: `go install github.com/canonical/spread/cmd/spread@latest` (optional - typically run in CI, not required for regular development) - Run spread tests: `spread` (from repository root) - Spread tests are defined in `task.yaml` files within test directories - Each test has `prepare`, `execute`, and optionally `restore` sections From 248dd581e0a9b4bc8ffc69c5b2772300a5e6f2f3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 6 Nov 2025 14:26:45 +0000 Subject: [PATCH 8/8] docs(agents): simplify CI section, use multipass backend, improve scope example Co-authored-by: lengau <4305943+lengau@users.noreply.github.com> --- agents.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/agents.md b/agents.md index 0fb048b2b..4d57ce4f7 100644 --- a/agents.md +++ b/agents.md @@ -112,7 +112,7 @@ The scope should indicate the component or area affected (e.g., `TestService`, ` Examples: -- `feat(TestService): add new validation method` +- `feat(models): add new validation method` - `feat(commands): add --verbose flag to pack command` - `fix(launchpad): resolve authentication timeout issue` @@ -246,13 +246,7 @@ Custom exceptions in `craft_application/errors.py`: ## Continuous Integration -GitHub Actions workflows are in `.github/workflows/`: - -- `qa.yaml`: Main quality assurance (lint, type check, test) -- `spread.yaml`: Spread integration tests -- `tics.yaml`: TICS quality analysis -- `policy.yaml`: Security and policy checks -- `release-publish.yaml`: Release automation +When you push changes, all GitHub Actions workflows in `.github/workflows/` should pass. These include quality assurance checks, spread integration tests, TICS analysis, security policy checks, and release automation. ## Documentation @@ -274,11 +268,10 @@ make docs # Build static documentation 1. **Always run setup first**: `make setup` ensures a clean development environment 2. **Test incrementally**: Run `make test` to validate changes -3. **Run spread tests locally**: Before committing, run spread tests using the LXD backend (if available and if making system-level changes). The default Google backend requires cloud credentials. To use LXD: - - Ensure LXD is installed: `sudo snap install lxd` - - Initialize LXD if needed: `sudo lxd init --minimal` - - Run spread with LXD: `spread lxd:` (the trailing colon runs all LXD-configured systems from spread.yaml) - - Note: LXD setup requires root/sudo access and may not work in all environments. Spread tests are optional for most development and will run in CI. +3. **Run spread tests locally**: Before committing, run spread tests using the multipass backend (if making system-level changes). To use multipass: + - Ensure multipass is installed: `sudo snap install multipass` + - Run spread with multipass: `spread multipass:` (the trailing colon runs all multipass-configured systems from spread.yaml) + - Note: Multipass setup requires snap and may not work in all environments. Spread tests are optional for most development and will run in CI. 4. **Format before committing**: `make format` or rely on pre-commit hooks 5. **Check types early**: Run `make lint` to catch type errors and other issues 6. **Reference existing code**: Look at similar implementations for patterns and style