Project layout

This section provides an overview of the key paths in your Salt extension project.

.copier-answers.yml

Stores Copier-specific data, including answers to template questions, the template’s source URI, and the last version the project was updated to.

Do not edit manually. To change your answers, use copier update --trust. To avoid updating the template version, pass the current version in vcs-ref.

.envrc.example

Example direnv configuration. Copy to .envrc to automate dev env setup and venv activation on shell entry.

.pre-commit-config.yaml

Configures the project’s pre-commit hooks: autoformatting, linting and docs generation.

.pre-commit-hooks

Project-local hook scripts, generating module docs and checking CLI examples.

CHANGELOG.md

Contains the project’s changelog. Update this file using towncrier instead of manually.

Makefile

Convenience targets for common development tasks, e.g. make dev (create/synchronize the dev venv), make tests, make docs, make changelog and make clean.

README.md

Provides a brief project overview and developer information. Includes a note about user documentation and, if docs_url was set, a link to the hosted documentation.

noxfile.py

Defines nox sessions for running tests, building documentation, and linting code.

pyproject.toml

Holds project metadata, package dependencies and configuration for tools used in the project’s lifecycle.

.github

Contains GitHub-related configurations and workflows. This directory is only present if your source_url is on GitHub.

.github/workflows

Houses GitHub Actions workflows. Besides the entry points described below, it contains reusable *-action.yml building blocks they delegate to.

.github/workflows/ci.yml

A meta-workflow that triggers other workflows related to testing and building.

.github/workflows/clear-caches.yml

Purges the repository’s GitHub Actions caches, either all of them or a single key. Triggered via manual dispatch.

.github/workflows/deploy-package-action.yml

A minimal standalone workflow publishing the built packages to Test PyPI and PyPI. Triggered when the release pipeline in tag.yml – or, without the autorelease app, tag-auto.yml – has concluded. Needs to be entered as the workflow when configuring Trusted Publishers. Subsequent release steps run in finalize-release-action.yml, outside the publishing trust boundary.

.github/workflows/finalize-release-action.yml

Finalizes a release after deploy-package-action.yml has published the packages: creates the GitHub release and deploys the documentation if configured. Kept separate to keep the Trusted Publisher workflow minimal.

.github/workflows/pr.yml

Handles Pull Requests. Delegates to workflows in ci.yml.

.github/workflows/prepare-release-action.yml

Creates/updates the autorelease PR. Called by push.yml, can also be dispatched manually (Prepare Release PR) to force a custom version or refresh the PR.

.github/workflows/push.yml

Handles pushes to the main branch. Includes workflows from ci.yml, creates the autorelease PR and can publish documentation.

.github/workflows/tag-auto.yml

Triggered by merging the autorelease PR. Validates the release and pushes the version tag. With the autorelease app configured, the tag is pushed using the app’s token, handing the release off to tag.yml. Otherwise, this workflow runs the release pipeline itself as an alternative entry point.

.github/workflows/tag.yml

Triggered by tag pushes for tags beginning with v, including those pushed by tag-auto.yml with the autorelease app’s token. Includes workflows from ci.yml. Separate workflows publish the built packages and finalize the release.

changelog

Directory containing news fragments for towncrier. Also includes the default version-specific changelog template in changelog/.template.jinja.

docs

Root directory for documentation-related files.

docs/conf.py

Contains Sphinx configuration and plugins.

docs/index.rst

Homepage for the documentation, (indirectly) linking to all other documentation files.

Hint

If your project includes a utils directory, manually add the corresponding documentation here (not handled by the Copier template or the pre-commit hook).

docs/ref

Directory containing autogenerated module documentation. Typically does not require manual updates, but can be used for custom documents, like a configuration reference.

docs/topics

Intended to hold high-level guides related to your Salt extension, such as Configuration. By default, includes an Installation guide.

src

Root directory for your Salt extension’s package.

src/<package>/utils/_types.py

Static typing helpers, only generated when typing is enabled: type aliases for common Salt objects and typed loader dunders for importing inside typing.TYPE_CHECKING blocks.

tests

Root directory for Pytest-based test modules.

tests/conftest.py

Provides default fixtures and basic test setup.

tests/functional

Contains functional tests.

tests/functional/conftest.py

Provides default fixtures for functional tests.

tests/integration

Contains integration tests.

tests/integration/conftest.py

Provides default fixtures for integration tests.

tests/unit

Contains unit tests.

tests/unit/conftest.py

Provides default fixtures for unit tests.

tools

Development automation scripts.

tools/initialize.py

Creates/synchronizes the development environment (first steps). Invoked via make dev, .envrc or directly.

tools/version.py

Infers the project version from the changelog and pending news fragments. Used by the release workflows.