Skip to content

Latest commit

 

History

History
80 lines (56 loc) · 3.73 KB

HACKING.rst

File metadata and controls

80 lines (56 loc) · 3.73 KB
Raw

Craft CLI

Welcome to Craft CLI! We hope this document helps you get started. Before contributing any code, please sign the Canonical contributor licence agreement.

Setting up a development environment

We use a forking, feature-based workflow, so you should start by forking the repository. Once you've done that, clone the project to your computer using git clone's --recurse-submodules parameter. (See more on the git submodules documentation.)

Tooling

We use a large number of tools for our project. Most of these are installed for you with tox, but you'll need to install:

  • Python 3.8 (default on Ubuntu 20.04, available on Ubuntu 22.04 through the deadsnakes PPA) with setuptools.
  • tox version 4 or later. (3.8+ will automatically provision a v4 virtualenv)
  • Pyright (it's recommended you install with snap install --classic pyright)
  • ShellCheck (also available via snap: snap install shellcheck)
  • pre-commit

Once you have all of those installed, you can install the necessary virtual environments for this repository using tox.

Other tools

Some other tools we use for code quality include:

  • Black for code formatting
  • pytest for testing
  • ruff for linting (and some additional formatting)

A complete list is kept in our pyproject.toml file in dev dependencies.

Initial Setup

After cloning the repository but before making any changes, it's worth ensuring that the tests, linting and tools all run on your machine. Running tox with no parameters will create the necessary virtual environments for linting and testing and run those:

tox

If you want to install the environments but not run the tests, you can run:

tox --notest

If you'd like to run the tests with a newer version of Python, you can pass a specific environment. You must have an appropriately versioned Python interpreter installed. For example, to run with Python 3.10, run:

tox -e test-py310

While the use of pre-commit is optional, it is highly encouraged, as it runs automatic fixes for files when git commit is called, including code formatting with black and ruff. The versions available in apt from Debian 11 (bullseye), Ubuntu 22.04 (jammy) and newer are sufficient, but you can also install the latest with pip install pre-commit. Once you've installed it, run pre-commit install in this git repository to install the pre-commit hooks.

Tox environments and labels

We group tox environments with the following labels:

  • format: Runs all code formatters with auto-fixing
  • type: Runs all type checkers
  • lint: Runs all linters (including type checkers)
  • unit-tests: Runs unit tests in Python versions on supported LTS's + latest
  • integration-tests: Same as above but for integration tests
  • tests: The union of unit-tests and integration-tests

For each of these, you can see which environments will be run with tox list. For example:

tox list -m lint

You can also see all the environments by simply running tox list

Running tox run -m format and tox run -m lint before committing code is recommended.