Creation

With Copier, creating a Salt extension project is easy:

copier copy --trust https://github.com/salt-extensions/salt-extension-copier my-awesome-new-saltext

You are then prompted with questions to configure your project structure. These answers are saved in .copier-answers.yml for future updates.

Important

Copier needs to be invoked with the --trust flag in order to enable custom Jinja extensions (always) and migrations (during updates). This effectively runs unsandboxed commands on your host, so ensure you trust the template source!

• Jinja extensions

• tasks and migrations

Important considerations

Organization vs single

Decide early whether to submit your project to the salt-extensions GitHub organization or host it in your own repository. This is determined by the source_url you provide.

GitHub vs other Git host (non-org)

If hosting the repository outside the organization, you can choose your provider freely. Note that the default workflows only work on GitHub though.

First steps

To finalize your project setup, ensure you initialize the Git repository and Python virtual environment and install and run the pre-commit hooks.

Initialize the repository

git init -b main

Important

Some automations assume your default branch is main. Ensure this is the case.

Initialize the Python virtual environment

python -m venv venv
source venv/bin/activate
python -m pip install -e '.[tests,dev,docs]'

This creates a virtual environment and installs relevant dependencies, including nox and pre-commit.

Install the pre-commit hook

python -m pre_commit install --install-hooks

This ensures pre-commit runs before each commit. It autoformats and lints your code and ensures the presence of necessary documentation files. To skip these checks temporarily, use git commit --no-verify.

First commit

git add .
git commit -m "Initial extension layout"

In case pre-commit modifies or creates files, the commit is aborted. Stage the changes and try again.