Usage¶

Prerequisites¶

Warning

Follow the installation instructions before proceeding.

Overview¶

Create an issue for the task.
Create a new branch (<issue-number> or similar).
(Optional) Add dependencies to pyproject.toml.
Write code in /src/<project_name> and tests in /tests.
Use git add, git commit (following semver ⧉), and git push.
pre-commit will guide you through the process.
Create a pull request (following semver ⧉).
Wait for CI checks and code review approval.

Tip

See CONTRIBUTING.md for details.

Git workflow¶

opentemplate follows an extended GitHub Flow ⧉:

Create or pick up an issue (task tracker).
Create a branch (<issue-number> or similar) to track changes.
Push your changes to the remote repository.
Open a pull request (PR title should follow semver ⧉, e.g., feat: add feature, fix: bugfix).

The main branch is protected and should always be in a releasable state.

Note

If a PR has a few commits, its type should match the most significant one (feat! > fix! > feat > fix).

Tip

The GitHub CLI ⧉ simplifies this process. A future extension will streamline it further.

Programming¶

Source code¶

Place project source code in src/<project_name> or at least src (e.g., src/infrastructure). Some exceptions apply (e.g., Dockerfile, Makefile).

Note

Before every commit and push pre-commit will run checks ensuring code quality and style.

Tests¶

Tests should be in /tests. The default framework is pytest, but you can change it in dev-test section inside pyproject.toml.

Key considerations:

100% test coverage is the default (recommended).
Fuzzing is encouraged (OSSF Scorecard ⧉); hypothesis ⧉ is included by default.

Note

opentemplate does not enforce a specific testing methodology (e.g., TDD, BDD).

Commits¶

opentemplate follows simplified semver ⧉:

Allowed types: fix, feat, BREAKING CHANGE.
No scopes (e.g., feat(actions): ... is incorrect).

Commits should be:

Signed-off (agreeing to the Developer Certificate of Origin ⧉).
Signed via GPG, SSH, S/MIME, or gitsign ⧉ (learn more ⧉).

Pull requests¶

Pull request type is determined by the most significant type of commit:

BREAKING CHANGE > feat > fix.
Pull requests will be labeled automatically with scopes (additional labels may be added manually).

Warning

Predefined labels exist; avoid creating new ones unless necessary.

Each pull request undergoes CI testing (similar to local tests). Depending on repository type and security settings, up to two reviewers may be required (as defined during installation).

Code sources¶

pyproject.toml
.pre-commit-config.yaml
.github/pr-labeler.yml
/.github/workflows/template_setup.yml
.github/workflows/python-tests.yml