# 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__](https://open-nudge.github.io/opentemplate/template/about/philosophy):
no tokens, no fees, no premium plans, open source software only
- [__Easy to use__](https://open-nudge.github.io/opentemplate/template/quickstart/usage):
clone templated repo, run `pdm setup` and __focus on your code__
- [__State of the art__](https://open-nudge.github.io/opentemplate/template/details):
best checkers for Python, YAML, Markdown, prose, and more unified
- [__Secure__](https://open-nudge.github.io/opentemplate/template/details/security):
[SLSA Level 3](https://slsa.dev/spec/v1.0-rc1/levels), [SBOMs](https://www.cisa.gov/sbom),
[attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds),
[secured egress](https://github.com/step-security/harden-runner),
[OSSF Best Practices](https://github.com/ossf/scorecard)
- [__Consistent__](https://open-nudge.github.io/opentemplate/template/configuration/basic):
common project metadata lives in `/project`, while tool configuration
stays shared by `GitHub Actions`, `prek`, and `pyproject.toml`
- [__Performant__](https://open-nudge.github.io/opentemplate/template/details/github-actions):
parallel checks, builds, minimally-sized caches and checkouts
> [!IMPORTANT]
> __An example repository using `opentemplate`
> [here](https://github.com/open-nudge/cogeol)__
> [!CAUTION]
> __All files in this repo will be copied to your project,
> using the title and description you provide.__
### Code quality (Python focused)
> [!IMPORTANT]
> __Adjust common project metadata from `/project`; use `pyproject.toml`
> for advanced tooling configuration.__
- __Package manager:__ [`pdm`](https://pdm-project.org/en/latest/)
with a single `pdm setup` manages everything!
(see [why pdm](https://open-nudge.github.io/opentemplate/latest/template/about/faq/#why-use-pdm-instead-of-uv))
- __Testing:__ [`pytest`](https://docs.pytest.org/en/stable/)
(with [`coverage`](https://coverage.readthedocs.io/en/7.9.1/),
and [`hypothesis`](https://hypothesis.readthedocs.io/en/latest/) for
fuzzing, doctests, and [`mutmut`](https://mutmut.readthedocs.io/en/latest/)
for mutation testing); __testing across all Python versions
done WITHOUT [`tox`](https://tox.wiki/en/4.27.0/)
or [`nox`](https://nox.thea.codes/en/stable/)__(managed directly by `pdm`!)
- __Documentation:__ [`mkdocs`](https://www.mkdocs.org/) -
__document once, have it everywhere (unified look on GitHub and hosted docs)__,
[semantically versioned](https://semver.org/)
(via [`mike`](https://github.com/jimporter/mike)),
autogenerated from
[coverage](https://github.com/econchick/interrogate),
[deadlink](https://github.com/AlexanderDokuchaev/md-dead-link-check)
and [spell-checked](https://github.com/codespell-project/codespell) docstrings,
automatically deployed after each GitHub release with clean
[material design look](https://github.com/squidfunk/mkdocs-material)
- __Code formatting and linting:__ [`ruff`](https://github.com/astral-sh/ruff)
(checks hand-picked for best quality and ease of use; most are enabled),
[`pyrefly`](https://github.com/facebook/pyrefly)
for type checking
- __Each file is copyrighted with your git information__ -
copyrights added automatically by `prek`,
see [REUSE](https://reuse.readthedocs.io/en/stable/) and
[SPDX Licensing](https://spdx.dev/learn/handling-license-info/)
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`](https://pypi.org/project/cogeol/))
according to [Scientific Python SPEC0](https://scientific-python.org/specs/spec-0000/)
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-` and `fix-` `pdm` commands__
- __Release to `PyPI` and `GitHub`__: done by making a
[GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases),
each release is attested and immutably versioned via
[`commition`](https://pypi.org/project/commition/)
- [__`prek`__](https://prek.j178.dev/): __all checks and fixers are run
before commit__, no need to remember them!
(`prek` 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__](https://open-nudge.github.io/opentemplate/latest/template/quickstart/installation/#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](https://github.com/open-nudge/opentemplate/issues/1)).
Best part? __`harden.yml` workflow, which does that
automatically__ (if you follow the instructions in the issue)!
- [__SLSA compliance__](https://slsa.dev/spec/v1.0-rc1/levels):
Level 3+ for public/enterprise repositories
and L2 for private repositories
via [slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator)
- __[Software Bills of Materials](https://www.cisa.gov/sbom) (SBOMs)__:
generated per-Python, per-OS, per-dependency group -
__each [attested](https://github.com/actions/attest)__,
and attached to the release
- __Static security analysis tooling__: [`osv-scanner`](https://github.com/google/osv-scanner)
checks against [OSV database](https://osv.dev/),
[`semgrep`](https://semgrep.dev/) monitors code quality and security,
[`zizmor`](https://github.com/zizmorcore/zizmor) verifies workflows,
while [`trufflehog`](https://github.com/trufflesecurity/trufflehog)
looks for leaked secrets
- __Reusable workflows__: most of the workflows are [reusable](https://docs.github.com/en/actions/sharing-automations/reusing-workflows)
(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, `prek` and `pdm.lock`)
- __Monitored egress in GitHub Actions__: [`harden-runner`](https://github.com/step-security/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](https://github.com/open-nudge/opentemplate/releases/tag/v0.1.3)
> 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`](https://github.blog/open-source/git/bring-your-monorepo-down-to-size-with-sparse-checkout/)
when possible to minimize the amount of data transferred;
__great for large repositories with many files and large history__
- __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](https://semver.org/) `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`](https://git-cliff.org/) - commits
automatically divided based on `labels`, `types`, human/bot authors,
and linked to appropriate issues and pull requests
- __Config files__: [editorconfig](https://editorconfig.org/), `.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](https://github.com/siderolabs/conform))
## Comparison
- Broader scope than other [`cookiecutter`](https://github.com/cookiecutter/cookiecutter)
templates (e.g. one-click and one-command setup, security,
GitHub Actions, comprehensive docs, rulesets. deprecation policies,
automated copyrights and more).
Check [here](https://github.com/fpgmaas/cookiecutter-uv)
or [here](https://github.com/audreyfeldroy/cookiecutter-pypackage)
to compare yourself.
- Truly FOSS (no freemium, no paid plans, no tokens) when compared to commercial
offerings like [`snyk`](https://snyk.io/) or
[`jit.io`](https://www.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](https://open-nudge.github.io/opentemplate/latest/template/about/comparison/)
## Quick start
### Installation
> [!NOTE]
> [Install `pdm`](https://pdm-project.org/en/latest/#recommended-installation-method)
> (if you don't have it already), for Linux/MacOS:
```sh
curl -sSL https://pdm-project.org/install-pdm.py | python3 -
```
1. Create a new GitHub repository using this template
(green `Use this template` button)
1. Name your repo (__use underscore `_`, not hyphens `-`__)
1. Add project description (__necessary!__)
1. __Wait until the setup commit appears__
(performed by `github-actions[bot]`, it may take a few minutes)
1. Clone the repository
1. Run `pdm setup` command locally to setup development environment
> [!TIP]
> For more details read the
> [documentation](https://open-nudge.github.io/opentemplate/template/quickstart/installation)
### Usage
1. Create a new branch
1. Optionally adjust project metadata in `/project`
(for example runtime dependencies in `project/dependencies.txt`;
no need to update `[project]` in `pyproject.toml` manually)
1. Write code in `/src/` and tests in `/tests`
1. Use `git add`, `git commit` and `git push` your changes
1. `prek` will guide you through the process
> [!TIP]
> For more details read the
> [documentation](https://open-nudge.github.io/opentemplate/template/quickstart/usage)
### Examples
> [!CAUTION]
> Click on each example to see it in action!
Run checkers or fixers manually (click me)
```sh
> pdm check- [FILE1, FILE2, ...] # pdm fix-
```
For example, to check __all Python files__:
```sh
> pdm check-python
```
Or to check `/src/__init__.py`:
```sh
> pdm check-python src/__init__.py
```
Note that all `check` and `fix` commands are grouped for your convenience:
```sh
> pdm check-all # pdm fix-all
```
Adjust template (click me)
> Common package metadata changes should go through `/project`;
> routine `[project]` edits in `pyproject.toml` are template boilerplate.
Common changes in `/project`:
- Add runtime dependencies in `project/dependencies.txt`
- Add package keywords in `project/keywords.txt`
- Add package classifiers in `project/classifiers.txt`
Advanced tool and development changes still belong in `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 `prek` and `GitHub Actions`__
Disable some prek check (click me)
> Disabling checks should be done cautiously!
`prek` checks are defined in `prek.toml`.
Disable a check using `SKIP` environment variable:
```sh
SKIP="," git commit -m
```
For example, the following will skip `DCO` and `ini` checks
and Python fixes (which would modify files):
```sh
SKIP="dco,ini,fix-python" git commit -m
```
For details, refer to the `id` fields in `prek.toml`.
> 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__.
## Contribute
We welcome your contributions! Start here:
- [Code of Conduct](/CODE_OF_CONDUCT.md)
- [Contributing Guide](/CONTRIBUTING.md)
- [Roadmap](/ROADMAP.md)
- [Changelog](/CHANGELOG.md)
- [Report security vulnerabilities](/SECURITY.md)
- [Open an Issue](https://github.com/open-nudge/opentemplate/issues)
## Legal
- This project is licensed under the _Apache 2.0 License_ - see
the [LICENSE](/LICENSE.md) file for details.
- This project is copyrighted by _open-nudge_ - the
appropriate copyright notice is included in each file.