Template questions¶

During project creation or when an update introduces a new variable, you will be prompted with some of the following questions:

`project_name`¶

The name of the project, particularly for PyPI.

The final name depends on no_saltext_namespace.

Example: vault

Important

Do not include the saltext. namespace here.

`author`¶

The main author’s name for PyPI package metadata and licensing.

Example: Foo Bar

`author_email`¶

A contact email address for PyPI package metadata.

Example: foo@b.ar

`integration_name`¶

The name of the integrated service, used in autogenerated documentation and README.

Example: HashiCorp Vault

`summary`¶

A short description of the project for PyPI metadata, documentation, and README.

Example: Salt extension for interacting with HashiCorp Vault

`url`¶

The project’s main URL for PyPI metadata, typically the hosted git repository.

Example: https://github.com/salt-extensions/saltext-vault

`source_url`¶

The URL of the hosted git repository for PyPI metadata.

Example: https://github.com/salt-extensions/saltext-vault

`tracker_url`¶

The URL of the issue tracker for PyPI metadata.

Example: https://github.com/salt-extensions/saltext-vault/issues

`package_name`¶

The Python package name used for importing. The final name depends on no_saltext_namespace.

Example: vault

Important

Do not include the saltext. namespace here.

`license`¶

Select a license. Any license other than Apache 2.0 requires manual management.

`license_classifier`¶

The license classifier for PyPI metadata.

Example: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)

Note

Only asked if a non-Apache license is selected.

`loaders`¶

Choose the Salt module types this extension should provide.

The generated module stubs scaffold the specifically named functions Salt expects for the corresponding module type, where applicable. See the Salt documentation on module types for details.

Note

The resource module type requires Salt 3008.0 or newer. The generated stub’s __virtual__ returns false on older releases, so selecting it does not prevent the extension from supporting older Salt versions.

The generated stub is a flat module, but a resource type can also be authored as a package (resources/<rtype>/__init__.py carrying the connection module) containing per-type loader overlay directories such as modules/ or states/. The docs and pre-commit tooling account for both shapes. Ensure each overlay directory contains an __init__.py, otherwise it is not included in built packages.

`salt_version`¶

The minimum Salt version to support. Influences package dependencies and versions that are tested against.

`python_requires`¶

The minimum Python version to support. Also affects pre-commit autoformatting hooks.

`max_salt_version`¶

The maximum Salt version to support. Influences the Salt versions tests are run against.

`venv_python`¶

Python version (MAJOR.MINOR) for the local development virtual environment. The default follows the latest supported Salt onedir release, which is the least likely to cause installation issues. Choose a different one if it is hard to come by on the target platform of your extension. Individual developers can override this locally via VENV_PYTHON.

`no_saltext_namespace`¶

Whether to use the saltext. namespace for the Python package.

`ssh_fixtures`¶

Include test fixtures for Salt-SSH tests (salt_ssh_cli etc.). Defaults to true if wrapper modules are included.

`test_containers`¶

Add support for running containers in the test suite (for functional and integration tests).

Note

In CI, a Docker daemon is only available on the GitHub-hosted Ubuntu runners (the Linux workflow job). Jobs running inside VMs – non-Ubuntu linux_test_distros and the BSD platforms – as well as the macOS and Windows runners don’t provide one, so ensure container-based tests are skipped when Docker is unavailable, e.g. via the skip_if_binaries_missing("docker") marker (pytest-skip-markers, a dependency of pytest-salt-factories).

`os_support`¶

Select supported operating systems. Usually, you should leave the default of Linux, macOS and Windows, but some extensions only make sense on specific systems.

This question influences on which systems the tests are run and which Operating System :: Trove classifiers are added to the package metadata.

Note

macOS and Windows tests run on native GitHub-hosted runners, Linux tests on the distributions selected in linux_test_distros. FreeBSD and OpenBSD tests run inside VMs on Linux runners. No Salt onedir builds exist for these platforms, so instead of a Salt version matrix, the tests run against the Salt release packaged by the OS, like Python itself. The project’s minimum Salt requirement acts as a lower bound: if the packaged release is older, the newest release satisfying it is installed from PyPI instead. This may fail because of missing build tools or libaries.

For speed, the prepared VM images are cached between CI runs. On the platforms testing against the OS-packaged Salt release – the BSDs and Alpine – the cached image includes the installed Salt itself. Since the cache is only invalidated when the preparation script changes (e.g. during template updates) or when GitHub evicts it, their tests can lag behind the currently packaged Salt release. To force a refresh, delete the corresponding ...-prep-... entries in your repository’s GitHub Actions caches. The other Linux distribution VMs are unaffected: they install the respective Salt version matrix leg during the test run (see linux_test_distros). Release builds are denied cache access entirely, so their VM-based test jobs always prepare the image from scratch.

`linux_test_distros`¶

Select the Linux distributions the test suite runs on. The default of Ubuntu is appropriate for most extensions, but distribution-specific ones can select the distributions they target instead (or additionally).

Ubuntu tests run on native GitHub-hosted runners (as the Linux workflow job), all other distributions run inside VMs on Linux runners. In contrast to the BSD platforms, Linux distribution VMs run a parametrized Salt/Python version matrix (like Windows and macOS, each tested Salt release is paired with the newest Python version its onedir builds ship, which is provisioned on demand by uv). Alpine is the exception: since neither Salt onedir builds nor musl wheels for important binary dependencies exist, its tests run against the OS-packaged Salt release, like on the BSD platforms (see os_support). Since each matrix job boots its own VM, consider the increased CI resource usage when selecting several distributions or releases.

The VMs don’t provide a container runtime, so container-based tests must be skipped there and only execute in the Ubuntu jobs (see test_containers).

Note

Not asked if Linux is not part of os_support.

`*_releases`¶

Each operating system/Linux distribution selected for testing via os_support or linux_test_distros (except macOS and Windows) comes with a corresponding question for the OS releases to test against, e.g. ubuntu_releases or freebsd_releases.

The selectable releases are limited to those that are still supported upstream (according to endoflife.date) and available in CI. They are refreshed regularly and template updates adjust your answers automatically:

If the default selection was chosen and has changed since, the new default is adopted.
Otherwise, releases that are not selectable anymore are removed from a custom selection. If no selected release remains, the question is asked again.

The default Ubuntu release follows the newest stable GitHub-hosted runner release. For VM-based platforms, a leading part of a release selects the newest matching one (e.g. 15 selects the latest 15.x release).

`deploy_docs`¶

Decide when to publish documentation to GitHub pages:

never: Don’t publish documentation.
release: Publish when a release is tagged. This ensures documentation is in sync with the released functionality.
rolling: Publish on push and tag events to the default branch. This ensures upcoming unreleased changes are displayed in the changelog.

Important

Ensure your GitHub Actions workflow is allowed to publish to your GitHub Pages site.

Note

The current workflows do not support versioned documentation.

Note

Not asked if source_url is not on GitHub.

`docs_url`¶

The URL for hosted documentation, typically your GitHub Pages URL if using deploy_docs.

Example: https://salt-extensions.github.io/saltext-vault/

`require_autorelease_app`¶

Whether the release workflows require a dedicated GitHub App for release automation (AUTORELEASE_CLID/AUTORELEASE_PRIV secrets).

Requiring the app simplifies the release workflows significantly: CI always runs on the autorelease PR and all releases are handled by the tag push workflow since the release tag is pushed using the app’s token.

If false, the workflows additionally support running with the default GitHub token, at the cost of a more complex release pipeline and no CI runs on the autorelease PR.

Note

Defaults to true for repositories inside the salt-extensions organization, where the app is configured organization-wide.

Note

Not asked if source_url is not on GitHub.

`coc_contact`¶

A contact email for Code of Conduct complaints.

Example: foo@b.ar

`copyright_begin`¶

The starting year of the copyright range.

Example: 2024

`relax_pylint`¶

Suppress some Pylint messages that can cause noise (consider-using-f-string) or be time-intense (too-many-*) or difficult (redefined-builtin, redefined-outer-name) to solve with legacy code.

Additionally suppresses unused-argument in the test suite, often caused by requesting fixtures in the function signature instead of using @pytest.mark.usefixtures. Note that the decorator does not work on fixtures requesting other fixtures.

`typing`¶

Add support for static type checking via ty.

This adds a pre-commit hook that typechecks the project (hook ID ty, alias typing), corresponding [tool.ty.*] configuration in pyproject.toml and a typing-extensions test dependency.

Since Salt injects global dunders like __salt__ into loader modules at runtime, static type checkers cannot resolve them by themselves. The template thus also generates a utils/_types.py module providing imports for common Salt dunder globals (such as __salt__, __opts__) and a SaltLogger class accounting for Salt’s custom log levels. The generated loader module stubs import the dunders they use inside if typing.TYPE_CHECKING blocks, a pattern you can extend as your modules grow. Which dunders are available – and what they contain – depends on the module type, see the Salt documentation on dunder dictionaries:

import logging
import typing

if typing.TYPE_CHECKING:
    from saltext.foo.utils._types import SaltLogger
    from saltext.foo.utils._types import __opts__
    from saltext.foo.utils._types import __salt__

log: "SaltLogger" = logging.getLogger(__name__)  # type: ignore

Template questions¶

project_name¶

author¶

author_email¶

integration_name¶

summary¶

url¶

source_url¶

tracker_url¶

package_name¶

license¶

license_classifier¶

loaders¶

salt_version¶

python_requires¶

max_salt_version¶

venv_python¶

no_saltext_namespace¶

ssh_fixtures¶

test_containers¶

os_support¶

linux_test_distros¶

*_releases¶

deploy_docs¶

docs_url¶

require_autorelease_app¶

coc_contact¶

copyright_begin¶

relax_pylint¶

typing¶

`project_name`¶

`author`¶

`author_email`¶

`integration_name`¶

`summary`¶

`url`¶

`source_url`¶

`tracker_url`¶

`package_name`¶

`license`¶

`license_classifier`¶

`loaders`¶

`salt_version`¶

`python_requires`¶

`max_salt_version`¶

`venv_python`¶

`no_saltext_namespace`¶

`ssh_fixtures`¶

`test_containers`¶

`os_support`¶

`linux_test_distros`¶

`*_releases`¶

`deploy_docs`¶

`docs_url`¶

`require_autorelease_app`¶

`coc_contact`¶

`copyright_begin`¶

`relax_pylint`¶

`typing`¶