From d04d869b214da00286c74027958b4be6ecf18062 Mon Sep 17 00:00:00 2001 From: JacobPEvans <20714140+JacobPEvans@users.noreply.github.com> Date: Fri, 22 May 2026 13:47:38 -0400 Subject: [PATCH 1/4] fix(ci): set python-version to released 3.13 in single-version jobs The lint, type-check, security, and docs jobs in ci.yml were pinned to Python 3.14 (unreleased at time of original edit, and an outlier vs the test matrix which covers 3.11/3.12/3.13). The step names also said 'Set up Python 3.12' while the version was actually 3.14, compounding the confusion. Pin to 3.13 (latest stable, top of the test matrix) and drop the version from the step name so future bumps don't desync the label. --- .github/workflows/ci.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 37491ad..eacff08 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -17,10 +17,10 @@ jobs: - name: Checkout code uses: actions/checkout@v6 - - name: Set up Python 3.12 + - name: Set up Python uses: actions/setup-python@v6 with: - python-version: "3.14" + python-version: "3.13" cache: 'pip' - name: Install dependencies @@ -44,10 +44,10 @@ jobs: - name: Checkout code uses: actions/checkout@v6 - - name: Set up Python 3.12 + - name: Set up Python uses: actions/setup-python@v6 with: - python-version: "3.14" + python-version: "3.13" cache: 'pip' - name: Install dependencies @@ -67,10 +67,10 @@ jobs: - name: Checkout code uses: actions/checkout@v6 - - name: Set up Python 3.12 + - name: Set up Python uses: actions/setup-python@v6 with: - python-version: "3.14" + python-version: "3.13" cache: 'pip' - name: Install dependencies @@ -94,10 +94,10 @@ jobs: - name: Checkout code uses: actions/checkout@v6 - - name: Set up Python 3.12 + - name: Set up Python uses: actions/setup-python@v6 with: - python-version: "3.14" + python-version: "3.13" cache: 'pip' - name: Install dependencies From 0b58c083e7734650e05cd718a78a4a87c36d4c5c Mon Sep 17 00:00:00 2001 From: JacobPEvans <20714140+JacobPEvans@users.noreply.github.com> Date: Fri, 22 May 2026 13:48:42 -0400 Subject: [PATCH 2/4] chore(deps): drop redundant safety, keep pip-audit as canonical scanner pip-audit is the PyPA-maintained advisory scanner pulling from the same PyPI advisory database (osv.dev). safety is the legacy duplicate from Pyup and carries its own transitive vulnerabilities (joblib, nltk) that have been blocking CI on all PRs. The CI workflow already only invokes pip-audit; safety was installed via the [dev] extra but never run. Removing it eliminates the false-positive vuln chain in transitive deps and shrinks the dev install. Refs #56. --- pyproject.toml | 1 - requirements-dev.txt | 1 - 2 files changed, 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 93ecea8..91ecfd1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,7 +26,6 @@ dev = [ "mypy>=1.16.1", # Security "bandit[toml]>=1.8.0", - "safety>=3.0.0", # Testing "pytest>=8.4.1", "pytest-cov>=6.2.0", diff --git a/requirements-dev.txt b/requirements-dev.txt index a6b0a7c..5686d34 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -10,7 +10,6 @@ mypy>=1.16.1 # Security bandit[toml]>=1.8.0 -safety>=3.0.0 pip-audit>=2.7.0 # Testing From 500dcd71282c78bb79935d29bed6297238985bb1 Mon Sep 17 00:00:00 2001 From: JacobPEvans <20714140+JacobPEvans@users.noreply.github.com> Date: Fri, 22 May 2026 13:49:00 -0400 Subject: [PATCH 3/4] chore(template): mark instantiation placeholders + add TEMPLATE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The pyproject.toml placeholders ('hello-world', 'Your Name', 'your.email@example.com') looked like committed defaults rather than intentional template tokens. Forks could ship without realizing they needed to change them. Replace with explicit REPLACE_ME tokens, add a header comment pointing at TEMPLATE.md, and add the checklist itself covering project rename, package rename, README badges, and CI slug updates. Also flag the ruff isort known-first-party list — it still references hello_world and needs to match the renamed package. --- TEMPLATE.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++ pyproject.toml | 9 +++++--- 2 files changed, 62 insertions(+), 3 deletions(-) create mode 100644 TEMPLATE.md diff --git a/TEMPLATE.md b/TEMPLATE.md new file mode 100644 index 0000000..bfbc673 --- /dev/null +++ b/TEMPLATE.md @@ -0,0 +1,56 @@ +# Template Instantiation Checklist + +This repo is a **fork-and-edit** Python project template. After forking, walk +through each item below before opening your first real PR. + +## 1. Project identity (`pyproject.toml`) + +Replace every `REPLACE_ME` token: + +- `name = "REPLACE_ME-project-name"` → kebab-case PyPI distribution name +- `authors = [{name = "REPLACE_ME Author", email = "replace-me@example.com"}]` +- `description = "REPLACE_ME — short project description"` +- `[tool.ruff.lint.isort] known-first-party = ["hello_world"]` → + match your actual package directory under `src/` + +## 2. Rename the package + +```bash +git mv src/hello_world src/ +``` + +Update any imports in `tests/` and elsewhere from `hello_world` to your +package name. + +## 3. Update README + +- Replace `python-template` references with your project name +- Replace the example `hello_world` import/run snippets +- Update the badge URLs (replace `JacobPEvans/python-template` with + `/`) +- Fix the Codecov token in the coverage badge (or remove it until you wire + up Codecov for the new repo) + +## 4. CI workflows (`.github/workflows/`) + +- `ci.yml` and `tests.yml` reference `JacobPEvans/python-template` in the + Codecov `slug:` — replace with `/` +- Confirm the Python `matrix` in `tests.yml` matches the versions you want + to support; the single-version jobs in `ci.yml` use the latest released + stable (`3.13`) — bump when you upgrade + +## 5. Strip template scaffolding + +Once everything is renamed and CI is green on your fork, delete this file: + +```bash +git rm TEMPLATE.md +git commit -m "chore: remove template instantiation checklist" +``` + +## Why fork-and-edit instead of Cookiecutter? + +The template doubles as a working repo for its own CI (linting, type checks, +security scans, coverage gating). Cookiecutter-style placeholders would +break that — the repo itself wouldn't be installable or testable. Fork +copies the working state; you edit it in place. diff --git a/pyproject.toml b/pyproject.toml index 91ecfd1..2deebd8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,14 +2,16 @@ requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" +# TEMPLATE: After forking, replace the placeholders below. +# See TEMPLATE.md for the full instantiation checklist. [project] -name = "hello-world" +name = "REPLACE_ME-project-name" version = "0.1.0" license = {text = "Apache-2.0"} authors = [ - {name = "Your Name", email = "your.email@example.com"}, + {name = "REPLACE_ME Author", email = "replace-me@example.com"}, ] -description = "A simple Python project template" +description = "REPLACE_ME — short project description" readme = "README.md" requires-python = ">=3.11" classifiers = [ @@ -202,6 +204,7 @@ convention = "google" max-complexity = 10 [tool.ruff.lint.isort] +# TEMPLATE: replace "hello_world" with the actual package name (matches src//). known-first-party = ["hello_world"] force-single-line = false lines-after-imports = 2 From b22f791bcac0c3cfae8f7fbc1978cce89c40d23e Mon Sep 17 00:00:00 2001 From: JacobPEvans <20714140+JacobPEvans@users.noreply.github.com> Date: Sat, 23 May 2026 21:58:17 -0400 Subject: [PATCH 4/4] docs(template): note __init__.py metadata in rename checklist Address gemini-code-assist review: the rename step renamed the package directory and import paths, but the package-level metadata (__author__, __email__, __version__) in src//__init__.py was left unmentioned. Those values are hardcoded to the template author and need to be replaced by every fork. Restructure step 2 as a bulleted list so the metadata reminder lives at the same level as the import update. --- TEMPLATE.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/TEMPLATE.md b/TEMPLATE.md index bfbc673..cf8cff7 100644 --- a/TEMPLATE.md +++ b/TEMPLATE.md @@ -19,8 +19,11 @@ Replace every `REPLACE_ME` token: git mv src/hello_world src/ ``` -Update any imports in `tests/` and elsewhere from `hello_world` to your -package name. +- Update any imports in `tests/` and elsewhere from `hello_world` to your + package name. +- Update package-level metadata in `src//__init__.py`: + `__author__`, `__email__`, and `__version__` are currently hardcoded + with the template author's information and must be replaced. ## 3. Update README