Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@ assignees: ''

---

For suspected vulnerabilities or exposed credentials, follow SECURITY.md instead of
opening a public issue. Sanitize logs, screenshots, notebooks, and traces; do not
include secrets, restricted data, or private operational details.

## Describe the Bug

A clear and concise description of what the bug is.
Expand Down Expand Up @@ -35,8 +39,9 @@ If applicable, add screenshots to help explain your problem.

Please complete the following information:
- OS: [e.g. Linux, Windows, macOS]
- Python Version: [e.g. 3.9, 3.10]
- Project Version: [e.g. 1.0.0]
- Runtime/tool versions (if applicable):
- Project version or commit:
- Hardware, scheduler, container image, or agent client (if applicable):

## Additional Context

Expand Down
20 changes: 17 additions & 3 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,29 @@ Please describe the tests that you ran to verify your changes. Provide instructi
- [ ] Test A
- [ ] Test B

## AI Assistance

> AI tools used: [Name the tools used to develop this PR, or write "None".]
>
> Scope of assistance: [Describe what they helped produce or review.]
>
> Human validation: [Describe how the author checked the AI-assisted work; human PR review is still required.]

## Checklist

The sensitive-information reminder below is optional scaffolding for adopting
repositories; the artifact review matters, not copying this checklist or policy text.

- [ ] I have removed secrets, local account names, identifying paths, and unnecessary personal identifiers from examples, logs, notebooks, and attachments, following [SECURITY.md](../SECURITY.md#credentials-and-sensitive-outputs); suspected vulnerabilities are reported privately
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have explained non-obvious behavior where needed
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests passed locally with my changes
- [ ] I have added appropriate validation (tests, schema/skill checks, or documentation checks), or explained non-applicability
- [ ] Applicable checks passed; I have stated untested platforms and any external calls or resource costs
- [ ] I have completed the AI Assistance section above, including "None" if applicable, and arranged human review
- [ ] Changes to workflows, tool authority, credentials, or deployment boundaries have been called out for review, if applicable
- [ ] Any dependent changes have been merged and published in downstream modules

## Screenshots (if applicable)
Expand Down
71 changes: 56 additions & 15 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,47 +5,85 @@ on:
branches: [ main, develop ]
pull_request:
branches: [ main, develop ]
workflow_dispatch:
inputs:
check_external_urls:
description: Check external documentation URLs (advisory only)
type: boolean
default: false

permissions:
contents: read

jobs:
documentation:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
persist-credentials: false

- name: Check spelling
uses: crate-ci/typos@4c8b7f51ca60df14e3c5ca82770dfbbe6c3dae85 # v1.52.0
with:
files: '*.md docs/'

- name: Check local documentation links
uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2
with:
args: --offline --include-fragments=anchor-only --no-progress '*.md' 'docs/**/*.md'

- name: Check external documentation URLs
if: github.event_name == 'workflow_dispatch' && inputs.check_external_urls
continue-on-error: true
uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2
with:
fail: false
args: --exclude-all-private --timeout 20 --max-retries 2 --no-progress '*.md' 'docs/**/*.md'

check-lock:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
persist-credentials: false

- name: Set up Python
uses: actions/setup-python@v5
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
python-version: '3.11'

- name: Install uv
uses: astral-sh/setup-uv@v3
uses: astral-sh/setup-uv@8d55fbecc275b1c35dbe060458839f8d30439ccf # v3

- name: Check uv.lock is up-to-date
run: uv lock --check

lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
persist-credentials: false

- name: Set up Python
uses: actions/setup-python@v5
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
python-version: '3.11'

- name: Install uv
uses: astral-sh/setup-uv@v3
uses: astral-sh/setup-uv@8d55fbecc275b1c35dbe060458839f8d30439ccf # v3
with:
enable-cache: true

- name: Sync dependencies
run: uv sync --group dev
run: uv sync --locked --group dev

- name: Lint with ruff
run: uv run ruff check .
run: uv run --locked ruff check .

- name: Format check with ruff
run: uv run ruff format . --check
run: uv run --locked ruff format . --check

test:
runs-on: ubuntu-latest
Expand All @@ -54,26 +92,29 @@ jobs:
python-version: ['3.11', '3.12', '3.13', '3.14']

steps:
- uses: actions/checkout@v4
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
persist-credentials: false

- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
python-version: ${{ matrix.python-version }}

- name: Install uv
uses: astral-sh/setup-uv@v3
uses: astral-sh/setup-uv@8d55fbecc275b1c35dbe060458839f8d30439ccf # v3
with:
enable-cache: true

- name: Sync dependencies
run: uv sync --group test
run: uv sync --locked --group test

- name: Run tests with pytest
run: uv run pytest --cov=basetemplate --cov-report=xml
run: uv run --locked pytest --cov=basetemplate --cov-report=xml

- name: Upload coverage to Codecov
uses: codecov/codecov-action@v4
if: vars.ENABLE_CODECOV == 'true'
uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4
with:
file: ./coverage.xml
flags: unittests
Expand Down
49 changes: 38 additions & 11 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
@@ -1,30 +1,57 @@
name: Publish

on:
# Uncomment to publish on version tags
# push:
# tags:
# - "v*"
release:
types: [published]

permissions:
contents: read

jobs:
build-publish:
build:
if: vars.ENABLE_PYPI_PUBLISH == 'true' && startsWith(github.event.release.tag_name, 'v')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
ref: ${{ github.sha }}
persist-credentials: false

- name: Set up Python
uses: actions/setup-python@v5
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
python-version: '3.11'

- name: Install uv
uses: astral-sh/setup-uv@v3
uses: astral-sh/setup-uv@8d55fbecc275b1c35dbe060458839f8d30439ccf # v3

- name: Check lock
run: uv lock --check

- name: Build package
run: uv build

- name: Publish to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
- name: Store distributions
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
with:
name: distributions
path: dist/
if-no-files-found: error

publish:
needs: build
runs-on: ubuntu-latest
environment: pypi
permissions:
id-token: write
steps:
- name: Retrieve distributions
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
with:
name: distributions
path: dist/

- name: Publish to PyPI with Trusted Publishing
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
with:
packages-dir: dist/
# Note: Set PYPI_API_TOKEN secret in repository settings
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,12 @@ celerybeat.pid

# Environments
.env
.env.*
!.env.example
!.env.template
!.env.*.example
!.env.*.template
.envrc.local
.venv
env/
venv/
Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added
- Initial repository setup with best practices template
- Spelling and local-link checks in the existing CI workflow, plus optional,
manual-only external URL checks whose results are advisory and non-blocking.

### Changed
- Separate the shared repository baseline from Python starter defaults, with
conditional requirements for skills, specifications, services, scientific workflows,
and content.
- Document non-destructive adoption, administrator setup, and support/reproducibility limits.
- Clarify that sensitive-information checks assess public artifacts, not the presence
of duplicated sanitization policies; repository-specific reminders are optional.

### Deprecated

Expand All @@ -19,6 +27,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed

### Security
- Harden CI with immutable action pins, read-only permissions, locked dependency
consumption, and opt-in external coverage reporting.
- Make publishing explicitly opt-in with a separate OIDC publishing job and document
required release/environment protections.
- Add operational trust-boundary, credential-handling, and sanitized-reporting guidance.

## [1.0.0] - 2026-05-19

Expand Down
20 changes: 17 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,13 @@ This project and everyone participating in it is governed by our [Code of Conduc

### Reporting Bugs

For suspected vulnerabilities or exposed credentials, use the private route in
[SECURITY.md](./SECURITY.md), not a public issue. Sanitize logs, notebooks, screenshots,
and traces before sharing; omit tokens, keys, local account names, identifying paths,
unnecessary personal identifiers, restricted data, and private operational details.
See [Credentials and Sensitive Outputs](./SECURITY.md#credentials-and-sensitive-outputs)
for the policy, placeholder examples, and permitted public attribution.

Before creating bug reports, please check the issue list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:

- **Use a clear and descriptive title**
Expand All @@ -32,10 +39,10 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme

### Pull Requests

- Follow the Python code style guidelines (see below)
- Follow the style and validation guidelines applicable to the changed artifacts
- Document new code based on the Documentation Styleguide
- End all files with a newline
- Avoid platform-dependent code
- Document platform-dependent behavior and the configurations actually tested
- Add tests for any new functionality
- Include appropriate commit messages

Expand Down Expand Up @@ -87,10 +94,17 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme

## Testing

- Write tests for all new features
- Add validation appropriate to new features or artifacts: code tests, schema fixtures,
skill checks, or documentation/example checks
- Ensure all tests pass before submitting a pull request
- Aim for high test coverage
- Use descriptive test names
- Keep quick checks separate from network, paid API, accelerator, and scheduler tests.
State external calls and resource requirements before asking contributors to run them.
- Changes to CI must preserve least privilege: do not run untrusted PR code with
secrets, in privileged `pull_request_target`/`workflow_run` contexts, or on persistent
privileged runners. Pin actions to reviewed full commit SHAs, enforce dependency
locks in consuming jobs, and update pins deliberately.

## Guidelines for AI/LLM-Assisted Contributions

Expand Down
Loading
Loading