opentemplate¶

Features¶

opentemplate is a Python template which is:

Truly open source ⧉: no tokens, no fees, no premium plans, open source software only
Easy to use ⧉: clone templated repo, run pdm setup and focus on your code
State of the art ⧉: best checkers for Python, YAML, Markdown, prose, and more unified
Secure ⧉: SLSA Level 3 ⧉, SBOMs ⧉, attestations ⧉, secured egress ⧉, OSSF Best Practices ⧉
Consistent ⧉: all pipelines (GitHub Actions, pre-commit) share the same pyproject.toml config
Performant ⧉: parallel checks, builds, minimally-sized caches and checkouts

Important

An example repository using opentemplate here ⧉

Caution

All files in this repo will be copied to your project, using the title and description you provide.

Code quality (Python focused)¶

Important

You can adjust everything from pyproject.toml level!

Package manager: pdm ⧉ with a single pdm setup manages everything! (see why pdm ⧉)
Testing: pytest ⧉ (with coverage ⧉, and hypothesis ⧉ for fuzzing); testing across all Python versions done WITHOUT tox ⧉ or nox ⧉(managed directly by pdm!)
Documentation: mkdocs ⧉ - document once, have it everywhere (unified look on GitHub and hosted docs), semantically versioned ⧉ (via mike ⧉), autogenerated from coverage ⧉, deadlink ⧉ and spell-checked ⧉ docstrings, automatically deployed after each GitHub release with clean material design look ⧉
Code formatting and linting: ruff ⧉ (checks hand-picked for best quality and ease of use; most are enabled), basedpyright ⧉ for type checking, FawltyDeps ⧉ for static dependency analysis
Each file is copyrighted with your git information - copyrights added automatically by pre-commit, see REUSE ⧉ and SPDX Licensing ⧉ for more information
Automated Python version updates: pyproject.toml (and GitHub Actions pipelines where necessary) are automatically updated to always use 3 latest Python versions (via cogeol ⧉) according to Scientific Python SPEC0 ⧉ deprecation and end-of-life policies
Other code linting: checks for YAML, Markdown, INI, JSON, prose, all config files, shell, GitHub Actions - all grouped as check-<group> and fix-<group> pdm commands
Release to PyPI and GitHub: done by making a GitHub release ⧉, each release is attested and immutably versioned via commition ⧉
pre-commit ⧉: all checks and fixers are run before commit, no need to remember them! (pre-commit is also setup after running a single pdm setup command!)

Security¶

Important

Everything below is already provided out of the box, one-click only!

Hardening ⧉: during setup, an automated issue is created to guide you step by step through enabling rulesets, branch protection, mandatory reviewers, necessary signatures etc. (see here for an example ⧉). Best part? harden.yml workflow, which does that automatically (if you follow the instructions in the issue)!
SLSA compliance ⧉: Level 3+ for public/enterprise repositories and L2 for private repositories via slsa-github-generator ⧉
Software Bills of Materials ⧉ (SBOMs): generated per-Python, per-OS, per-dependency group - each attested ⧉, and attached to the release
Static security analysis tooling: osv-scanner ⧉ checks against OSV database ⧉, semgrep ⧉ monitors code quality and security, zizmor ⧉ verifies workflows, while trufflehog ⧉ looks for leaked secrets
Reusable workflows: most of the workflows are reusable ⧉ (pointing to opentemplate workflows) to improve security and get automated pipeline updates - you can make them local by running .github/reusability/localize.sh script. No need to manage/update your own workflows!
Pinned dependencies: all dependencies are pinned to specific versions (GitHub Actions, pre-commit and pdm.lock)
Monitored egress in GitHub Actions: harden-runner ⧉ with a whitelisted minimal set of domains necessary to run the workflows
Security documentation: SECURITY.md, SECURITY-INSIGHTS.yml, SECURITY-SELF-ASSESSMENT.md (only security file to update manually before release), and SECURITY-DEPENDENCY.md define high quality security policies

Tip

See this example release ⧉ for all security artifacts described above.

Note

Although there is around 100 workflows helping you maintain high quality, most of them reuse the same workflow, which makes them maintainable and extendable.

GitHub¶

GitHub Actions cache - after each merge to the main branch, dependencies are cached per-group and per-OS for maximum performance
Minimal checkouts and triggers - each workflow is triggered based on appropriate path and performs sparse-checkout ⧉ when possible to minimize the amount of data transferred; great for large repositories with many files and large history
Dependency updates: Renovate ⧉ updates all dependencies in a grouped manner once a week
Templates: every possible template included (discussions, issues, pull requests - each extensively described)
Predefined labels - each pull request will be automatically labeled (over 20 labels created during setup!) based on changed files (e.g. docs, tests, deps, config etc.). No need to specify semver ⧉ scope of commit anymore!
Open source documents: CODE_OF_CONDUCT.md, CONTRIBUTING.md, ROADMAP.md, CHANGELOG.md, CODEOWNERS, DCO, and much more - all automatically added and linked to your Python documentation out of the box
Release changelog: git-cliff ⧉ - commits automatically divided based on labels, types, human/bot authors, and linked to appropriate issues and pull requests
Config files: editorconfig ⧉, .gitattributes, always the latest Python .gitignore etc.
Commit checks: verification of signatures, commit messages, DCO signing, no commit to the main branch policy (via conform ⧉)

Comparison¶

Broader scope than other cookiecutter ⧉ templates (e.g. one-click and one-command setup, security, GitHub Actions, comprehensive docs, rulesets. deprecation policies, automated copyrights and more). Check here ⧉ or here ⧉ to compare yourself.
Truly FOSS (no freemium, no paid plans, no tokens) when compared to commercial offerings like snyk ⧉ or jit.io ⧉. Additionally Python-centric and sticks with tools widely known by developers (their own environment and GitHub interface).

Tip

See detailed comparison in the documentation ⧉

Quick start¶

Installation¶

Note

Install pdm ⧉ (if you don't have it already), for Linux/MacOS:

curl -sSL https://pdm-project.org/install-pdm.py | python3 -

Create a new GitHub repository using this template (green Use this template button)
Name your repo (use underscore _, not hyphens -)
Add project description (necessary!)
Wait until the setup commit appears (performed by github-actions[bot], it may take a few minutes)
Clone the repository
Run pdm setup command locally to setup development environment

Tip

For more details read the documentation ⧉

Usage¶

Create a new branch
Optionally add dependencies to pyproject.toml
Write code in /src/<project_name> and tests in /tests
Use git add, git commit and git push your changes
pre-commit will guide you through the process

Tip

For more details read the documentation ⧉

Examples¶

Caution

Click on each example to see it in action!

Run checkers or fixers manually (click me)

> pdm check-<group> [FILE1, FILE2, ...] # pdm fix-<group>

For example, to check __all Python files__:

> pdm check-python

Or to check `/src/__init__.py`:

> pdm check-python src/__init__.py

Note that all `check` and `fix` commands are grouped for your convenience:

> pdm check-all # pdm fix-all

Adjust template (click me)

> Most of the adjustments can be done by __only__ editing `pyproject.toml` Common changes to `pyproject.toml`: - Add dev dependencies under `[dependency-groups]` (everything is named `dev-`) - Modify `[tool.pdm.scripts]` for custom command (`check-` or `fix-`, the latter modifies files) - Use `[tool.]` to adjust specific tool configuration > __Adjusting these sections will affect `pre-commit` and `GitHub Actions`__

Disable some pre-commit check (click me)

> Disabling checks should be done cautiously! `pre-commit` checks are defined in `.pre-commit-config.yaml`. Disable a check using `SKIP` environment variable:

SKIP="<group1>,<group2>" git commit -m <message>

For example, the following will skip `DCO` and `ini` checks and Python fixes (which would modify files):

SKIP="dco,ini,fix-python" git commit -m <message>

For details, refer to the `id` fields in `.pre-commit-config.yaml`. > Some commands have both `-fix` and `-check` > for different actions!

Disable GitHub Actions checks (click me)

> Disabling checks should be done cautiously! When making a commit you can add one of the following strings to the message: - `[skip ci]` - `[ci skip]` - `[no ci]` - `[skip actions]` - `[actions skip]` > Note that you can also merge pull requests __even if the checks fail__.