Welcome to BaseTemplate! This guide will help you get started with this project.
For a new repository, use the starter files that fit your project. For an existing repository or organization transfer, apply the baseline in place: preserve history, layout, interfaces, and qualified dependency stacks.
- Replace template package names, URLs, contacts, acknowledgments, and support/version statements with accurate project-specific values. Confirm the security contact and response commitment before publishing them.
- Select the applicable requirements and document any non-applicability. Keep Python package files, coverage, and the CI Python matrix only when appropriate.
- Review public artifacts against the shared sensitive-information guidance. Do not require a separate sanitization policy in each repository. Links and local reminders are optional; add workflow-specific instructions when useful.
- Adapt CI to the project's real validation commands. Pin external actions to reviewed full commit SHAs and maintain those pins with dependency-update automation.
- The existing CI workflow checks spelling and local Markdown links/fragments on
pushes and pull requests. External URL checking is optional: manually run CI and
select
check_external_urlsto enable it (off by default). Results appear in the job summary but do not fail the job or workflow, even if the checker itself errors. External URL checks never run automatically. - Keep external reporting opt-in. The CI example uploads coverage to Codecov only
when the repository variable
ENABLE_CODECOVistrue; review what is sent first. - Publishing is opt-in. Remove the publish workflow for non-packages. For PyPI, first
configure a Trusted Publisher matching this repository,
publish.yml, and thepypienvironment. Protect release tags and configure environment approval/release-tag restrictions, then set the repository variableENABLE_PYPI_PUBLISHtotrue. The example builds on a publishedv*tag release and publishes those artifacts from a separate OIDC-enabled job, without a long-lived API token. - Document external calls, data flows, resource costs, and operational limits before users run examples; see the security guidance.
Repository files do not enforce GitHub settings. An administrator should verify:
- Required human approvals and status checks on the default branch, review ownership
for workflows and other sensitive paths (for example via
CODEOWNERS), and restricted bypass/force-push and release permissions. - Private vulnerability reporting where available, a monitored fallback contact, dependency alerts, secret scanning, and push protection. Review supported secret patterns and permitted bypasses; scanners do not detect every secret.
- Least-privilege workflow permissions, approval for untrusted contributors, and no untrusted PR execution on persistent or privileged HPC/self-hosted runners.
- Regular maintainer-access reviews and the organization's MFA policy.
- Protected publishing environments and release tags before enabling publication.
Record which controls were verified, by whom, and when. A checked-in checklist is not proof that live settings are enabled.
The following instructions apply to the included Python example.
- Python 3.11 or higher
- uv (Python package manager)
- git (for version control)
git clone https://github.com/AI-ModCon/BaseTemplate.git
cd basetemplateuv syncFor development work, use the same uv environment and run tools through it:
uv sync --group dev --group testuv run pytestRun tests with coverage:
uv run pytest --cov=basetemplate --cov-report=html --cov-report=term-missingWe use Ruff for both linting and formatting.
uv run ruff format .uv run ruff check .Ruff handles import sorting as part of formatting and linting, so there is no separate isort step.
For more detailed documentation, see the docs directory.
If you encounter issues with the virtual environment:
# Recreate the environment from the lockfile
uv syncIf you have issues installing dependencies, run uv sync again to refresh the environment.
- Read the Contributing Guidelines
For questions or issues, please open a GitHub issue or check the FAQ.