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!

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

Before hacking away on your new Salt extension, you need to initialize a Git repository and set up a development environment.

Contributors to existing Salt extension projects need to do the latter after cloning.

Automatic

Added in version 0.4.0.

This process is automated completely in the following cases:

  • For maintainers: When creating/updating a project via Copier, unless SKIP_INIT_MIGRATE=1 was set in the environment (repo initialization + dev env setup + pre-commit hook installation + running pre-commit).

  • For all developers: If you have a working direnv installation, you can copy the included .envrc.example to .envrc and allow it to run. This takes care of the dev env setup and pre-commit hook installation as well as activating the virtual environment. Without direnv, you can also run make dev to create/update the development environment. Remember to activate it via source .venv/bin/activate afterwards.

Important

The automation either requires uv or the Python version (MAJOR.MINOR) listed here to be available on your system, at the time of writing Python 3.10.

Hint

Without direnv or make, you can still call the automation script manually after entering the project root directory:

python3 tools/initialize.py
source .venv/bin/activate

Manual

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

Important

To create the virtualenv, it is recommended to use the same Python version (MAJOR.MINOR) as the one listed here, at the time of writing Python 3.10.

python3.10 -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.