From 321b21803fc3218dbb5200bf32a8b55f1b8c4e61 Mon Sep 17 00:00:00 2001 From: Marius Helf Date: Fri, 14 Aug 2026 18:06:59 +0000 Subject: [PATCH 1/3] Materialize signed-off spec for #8 --- spec/issue-8.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 spec/issue-8.md diff --git a/spec/issue-8.md b/spec/issue-8.md new file mode 100644 index 0000000..2442f84 --- /dev/null +++ b/spec/issue-8.md @@ -0,0 +1,81 @@ +Should be `ci.yaml` for more precise naming. + +--- + +## Spec + +**What:** Rename `template/.github/workflows/cicd.yaml` → `template/.github/workflows/ci.yaml`, +change its internal `name: CI/CD` → `name: CI`, and update the two references to the old filename: +`template/.github/workflows/release.yaml:28` (`uses: ./.github/workflows/cicd.yaml`) and the badge +in `template/README.md.jinja:3`. No `_migrations` entry, no test changes beyond keeping the suite +green. + +**Why:** The workflow contains only `lint`, `test` and `docs` jobs — there is no deployment in it. +Releasing lives in `release.yaml` and publishing in `publish.yaml`, so `cicd.yaml` / `name: CI/CD` +claims a responsibility the file does not have, and generated projects inherit that misnomer. `ci` +is what the file actually is, and it matches this repo's own `.github/workflows/ci.yaml`. + +### Copier-update behaviour (the open question, answered) + +Verified empirically with copier 9.11.3 by generating a project from `origin/main`, committing the +rename in a template clone, and running `copier update`: + +- **A clean `copier update` does perform the rename.** `cicd.yaml` is deleted, `ci.yaml` is created, + and the `release.yaml` / `README.md` references are rewritten. This holds whether or not the + template carries git tags. **So this ticket needs no `_migrations` entry.** +- **A downstream project's local edits to `cicd.yaml` are silently dropped** — they are not carried + into `ci.yaml`, and no conflict or `.rej` file is produced. Recoverable from the project's own git + history, but the update will not warn. +- Two pre-existing template defects gate the above; both are **out of scope here** (see below) and + neither blocks this rename: + 1. The template ships no `{{ _copier_conf.answers_file }}.jinja`, so generated projects have no + `.copier-answers.yml` and `copier update` refuses to run at all: *"Cannot update because cannot + obtain old template references from `.copier-answers.yml`."* Every project generated to date is + therefore un-updatable, which is why this rename cannot strand anyone today. + 2. `_tasks` (`git init`, `git checkout -b main`) also run on `update` and fail there + (`fatal: a branch named 'main' already exists`, exit 128). The abort lands *after* `ci.yaml` is + written and *before* `cicd.yaml` is deleted — a half-applied rename leaving both files, with the + stale `cicd.yaml` still triggering on `push`/`pull_request` and producing duplicate CI runs. + +### Notes for the implementer + +- Use `git mv` so the rename is recorded as a rename. +- `cicd.yaml` has no `.jinja` suffix and is copied verbatim (`_templates_suffix: .jinja`); keep it + that way — its `${{ matrix.python-version }}` would collide with Jinja. +- Branch rulesets require **job** names (`lint`, `test`, `docs`), which do not change, so no ruleset + breaks. The README **badge URL is per-filename**, so existing generated projects keep a badge + pointing at `cicd.yaml` until they re-render; acceptable, and noted rather than mitigated. +- #7 (CI gate) edits the same file and declares this rename out of its own scope — whichever lands + first, the other rebases. Not a dependency. + +## Acceptance criteria + +- [ ] `template/.github/workflows/ci.yaml` exists with the previous `cicd.yaml` content and no + `.jinja` suffix; `template/.github/workflows/cicd.yaml` no longer exists. +- [ ] The rename is recorded as a rename in the commit (`git show --stat` shows R, not add+delete). +- [ ] `ci.yaml` line 1 reads `name: CI`. +- [ ] `template/.github/workflows/release.yaml` uses `./.github/workflows/ci.yaml`. +- [ ] The `Tests` badge in `template/README.md.jinja` points at `actions/workflows/ci.yaml` in both + the image URL and the link target. +- [ ] `git grep -i cicd` returns nothing under `template/`. +- [ ] `uv run pytest tests` is green. +- [ ] Commit uses a `refactor:` prefix and carries no AI attribution trailer. + +## Out of scope + +- Shipping `{{ _copier_conf.answers_file }}.jinja` so generated projects become updatable (defect 1 + above) — its own ticket. +- Guarding `_tasks` with `when: "{{ _copier_conf.operation == 'copy' }}"` so `copier update` is not + aborted by `git init` / `git checkout -b main` (defect 2 above) — its own ticket. +- Renaming the `template/docs/source/contributing/ci_cd.md` stub or its `# CI/CD` heading: that page + documents the whole pipeline including release and publish, so its name is not the misnomer. +- Any `_migrations` entry — the empirical result above shows the rename propagates without one. + +## Verification + +```bash +uv run pytest tests # needs network; renders a project and runs its lint/test/pre-commit +git grep -i cicd -- template/ ; echo "exit=$?" # expect no matches +``` + +No `Depends-on:` — every file this spec touches is present on `origin/main`. From 9515c31889905b2d15190afa4b7fed6714d0c6f5 Mon Sep 17 00:00:00 2001 From: Marius Helf Date: Fri, 14 Aug 2026 20:08:40 +0200 Subject: [PATCH 2/3] refactor: rename template cicd.yaml to ci.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The workflow contains only lint, test and docs jobs — there is no deployment in it. Releasing lives in release.yaml and publishing in publish.yaml, so `cicd.yaml` / `name: CI/CD` claimed a responsibility the file does not have, and generated projects inherited that misnomer. Rename the file to ci.yaml, set `name: CI`, and update the two references to the old filename: the `uses:` in release.yaml and the Tests badge in README.md.jinja. The file keeps its verbatim (non-.jinja) status. A clean `copier update` performs the rename on its own, so no `_migrations` entry is needed. Branch rulesets pin job names (lint, test, docs), which are unchanged. Existing generated projects keep a badge pointing at cicd.yaml until they re-render. Closes #8 --- template/.github/workflows/{cicd.yaml => ci.yaml} | 2 +- template/.github/workflows/release.yaml | 2 +- template/README.md.jinja | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename template/.github/workflows/{cicd.yaml => ci.yaml} (99%) diff --git a/template/.github/workflows/cicd.yaml b/template/.github/workflows/ci.yaml similarity index 99% rename from template/.github/workflows/cicd.yaml rename to template/.github/workflows/ci.yaml index a4c5dff..794cb23 100644 --- a/template/.github/workflows/cicd.yaml +++ b/template/.github/workflows/ci.yaml @@ -1,4 +1,4 @@ -name: CI/CD +name: CI on: push: diff --git a/template/.github/workflows/release.yaml b/template/.github/workflows/release.yaml index df3e63e..4fca695 100644 --- a/template/.github/workflows/release.yaml +++ b/template/.github/workflows/release.yaml @@ -25,7 +25,7 @@ on: jobs: ci: - uses: ./.github/workflows/cicd.yaml + uses: ./.github/workflows/ci.yaml release: needs: ci diff --git a/template/README.md.jinja b/template/README.md.jinja index a88dd0d..2912efb 100644 --- a/template/README.md.jinja +++ b/template/README.md.jinja @@ -1,6 +1,6 @@ # {{ project_name }} -[![Tests](https://github.com/{{ github_username }}/{{ project_slug }}/actions/workflows/cicd.yaml/badge.svg)](https://github.com/{{ github_username }}/{{ project_slug }}/actions/workflows/cicd.yaml) +[![Tests](https://github.com/{{ github_username }}/{{ project_slug }}/actions/workflows/ci.yaml/badge.svg)](https://github.com/{{ github_username }}/{{ project_slug }}/actions/workflows/ci.yaml) [![PyPI version](https://badge.fury.io/py/{{ project_slug | replace('_', '-') }}.svg)](https://pypi.org/project/{{ project_slug | replace('_', '-') }}/) From bd38693a83f5b3ab44a038022a814d4326a3f7fd Mon Sep 17 00:00:00 2001 From: Marius Helf Date: Fri, 14 Aug 2026 20:56:39 +0200 Subject: [PATCH 3/3] test: update references to renamed ci.yaml workflow The template's cicd.yaml was renamed to ci.yaml in the previous commit. Tests must be updated to reference the new filename in both the CI_WORKFLOWS list and the assertion for local workflow references. --- tests/test_template.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/test_template.py b/tests/test_template.py index f1c1849..e971b86 100644 --- a/tests/test_template.py +++ b/tests/test_template.py @@ -18,11 +18,11 @@ # Both CI workflows carry the aggregate `ci-gate` job. They can be parsed # straight from disk: `_templates_suffix: .jinja` means only `.jinja` files are -# rendered, so the template's cicd.yaml is copied verbatim (which is also why +# rendered, so the template's ci.yaml is copied verbatim (which is also why # its `${{ matrix.python-version }}` survives generation). CI_WORKFLOWS = [ TEMPLATE_ROOT / ".github" / "workflows" / "ci.yaml", - TEMPLATE_ROOT / "template" / ".github" / "workflows" / "cicd.yaml", + TEMPLATE_ROOT / "template" / ".github" / "workflows" / "ci.yaml", ] @@ -310,7 +310,7 @@ def test_generated_release_keeps_local_workflow_ref_unpinned(project): for path, _, ref, _ in _uses_refs(project.path / ".github" / "workflows") if ref.startswith("./") ] - assert local == [("release.yaml", "./.github/workflows/cicd.yaml")] + assert local == [("release.yaml", "./.github/workflows/ci.yaml")] def test_default_slug_is_valid_package_name(tmp_path):