CONTRIBUTING.md

Set up the development environment

We recommend uv for setting up your local development environment:

• uv snap
• Official uv binary

To set up a local copy of the repository for development:

git clone https://github.com/canonical/charmcraft.git
cd charmcraft
make setup

If you need python-apt, add https://people.canonical.com/~lengau/pypi/ as an extra index URL.

You will need a copy of ruff installed. On many Linux distributions, you can install ruff with:

sudo snap install ruff

Otherwise, you can install ruff in your virtual environment with:

uv tool install ruff

Develop for the Charmcraft source

Make changes as appropriate. Some existing ideas are in the Github Issues

To test locally:

CHARMCRAFT_DEVELOPER=1 python -m charmcraft

When you're done, make sure you run the tests.

You can do so with:

uv sync
uv run pytest

Contributions welcome!

Contribute to the documentation

Charmcraft stores its documentation source in the repository and tests it for errors. Contributing to the documentation is similar to contributing to the code.

Before you begin, set up the development environment.

Write the docs

The Charmcraft documentation follows Diátaxis, and adheres to the conventions of the Canonical Documentation Style Guide.

The documentation source is written in reStructuredText, and is formatted according to Canonical's reStructuredText style. It uses Sphinx for linting and building, and employs the Intersphinx extension to link to the related Juju and ops library documentation.

Build the docs

After you've made changes to the documentation, it's a good practice to generate it locally so you can verify that the results look and feel correct.

You can preview the entire documentation set with your changes by building it as a website:

make docs

To view the rendered website, open docs/_build/index.html in a web browser. More changes to the files require you to rebuild.

You can also host the docs on an interactive server on your local system:

make docs-auto

The server can be reached at 127.0.0.1:8080 in a web browser. The server dynamically loads any changes you save to the documentation files, so you don't have to manually re-build every time you make a change.

Test your work

Once you've completed your draft, run a local test to make sure your changes follow the coding and documentation conventions:

make lint-docs

Please fix any errors the linter detects before submitting your changes for review.