opentemplate

All-in-one Python template. One click. Everything included.

✨ Features 🚀 Quick start 📚 Documentation 🤝 Contribute 👍 Adopters 📜 Legal

---

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 -

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

Tip

For more details read the documentation

Usage

1. Create a new branch
2. Optionally add dependencies to pyproject.toml
3. Write code in /src/<project_name> and tests in /tests
4. Use git add, git commit and git push your changes
5. 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-<group>)
• Modify [tool.pdm.scripts] for custom command (check-<group> or fix-<group>, the latter modifies files)
• Use [tool.<name>] 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 <group>-fix and <group>-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.

Contribute

We welcome your contributions! Start here:

• Code of Conduct
• Contributing Guide
• Roadmap
• Changelog
• Report security vulnerabilities
• Open an Issue

Legal

• This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
• This project is copyrighted by open-nudge - the appropriate copyright notice is included in each file.