A Copier template that initializes a project structure for developing Salt extension modules.
The template files themselves are based on the official create-salt-extension tool, with several updates submitted as a PR. This template provides the necessary scaffolding to render them via Copier (which does not require ugly hacks for this like Cookiecutter+Cruft).
I would like to keep this mostly in sync/slightly ahead of upstream.
With the amount of extensions that could be created in the future, I think it is relevant to ensure they have a frictionless way of keeping the necessary boilerplate up to date. I have used this method before for my numerous formulae via cruft
and am quite happy.
At least Copier version 9.1.0
is required (for multiselect functionality). It is generally recommended to install it via pipx
:
pipx install copier
Furthermore, since this template provides some Jinja extensions, you need to ensure copier-templates-extensions is present in the copier
virtual environment:
pipx inject copier copier-templates-extensions
Note that copier
has to be invoked with the --trust
flag because of the included Python code that runs during template rendering. Please verify for yourself that it does not do anything nasty.
Now, creating an extension project is as simple as running:
copier copy --trust https://github.com/lkubb/salt-extension-copier saltext-example
You are then presented with several questions, after which the project skeleton should be available. It additionally contains a .copier-answers.yml
file with the inputs you gave and the commit ref of the template repository that was used when creating it. You should commit it together with the project.
For specifics, please see the rendered README.md
instructions. The following describes the general workflow with notes:
Inside your project directory, initialize a git repository:
git init
Ensure you create a virtual environment for your extension and source it:
python -m venv venv --prompt 'saltext-example'
source venv/bin/activate
Then, install the project inside the created environment in editable mode. This needs to be run inside a git repository, so ensure you have initialized it at this point:
python -m pip install -e '.[tests,dev,docs]' # zsh requires the quotes
Ensure the pre-commit hook is installed:
pre-commit install
Then, you are ready to commit:
git add . && git commit -m "Initial commit"
Note that the pre-commit hooks might modify or create some files, which makes it fail. Just re-execute the command and all should be set.
Future boilerplate updates can be as simple as:
copier update --trust --skip-answered
In case you want to update your answers to the questions as well as update:
copier update --trust
To just change your answers without updating, you need to specify the git ref found in your .copier_answers.yml
:
copier update --trust --vcs-ref=$ref
Note that manually changing the inputs in the file is strongly discouraged by Copier.
Existing projects can be migrated to this template by simply running the creation command over a clone of the existing repository. You should specify the 0.0.2
tag as a reference at the moment since this template diverges from the latest official release (0.24.0
) after that.
git clone https://github.com/salt-extensions/saltext-example
copier copy --trust --vcs-ref=0.0.2 https://github.com/lkubb/salt-extension-copier saltext-example
You are then presented with the same questions as during initialization. copier
asks about conflict resolutions and afterwards creates .copier-answers.yml
. There have likely been several modifications to the boilerplate since the extension was generated, so this can require some attention and could even reintroduce older dependencies. In the next step, you should thus update the project to a more recent version.
The latest version of this template differs from the latest salt-extension 0.24.0
in the following ways:
- Updated dependencies, pre-commit hooks and workflow actions
- Salt and Python versions are parametrized all over the template
- Dropped support for Python 3.5/3.6 completely
- Contains functional tests skeleton,
(master|minion)_opts
fixtures for unit tests and optionally fixtures forsalt-ssh
tests - Removes pinning of test/docs/lint requirements (related issue) and the corresponding files
- Transitions to using
pyproject.toml
instead ofsetup.cfg
- The official tool is found here: https://github.com/saltstack/salt-extension
- The
salt-extensions
organization: https://github.com/salt-extensions copier
docs: https://copier.readthedocs.io/en/latest/- An overview of modular systems in Salt: https://docs.saltproject.io/en/latest/topics/development/modules/index.html
- The Salt-specific
pytest
docs: https://pytest-salt-factories.readthedocs.io/en/latest/