From 67c901263002e9c35d6be51a89c9e3bd7bfe5c7c Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:27:48 -0500 Subject: [PATCH 01/28] docs(04): mark Phase 4 (Backlog Triage) complete via manual pass Maintainer triaged the github.com/datafolklabs/cement backlog directly (80 open issues, 14-year tail) outside the GSD workflow rather than producing CONTEXT/PLAN/VERIFICATION artifacts. Records the closure comment template used and per-requirement disposition in 04-NOTE.md; flips TRIAGE-01..04 to Closed and updates ROADMAP/STATE accordingly. Co-Authored-By: Claude Opus 4.7 (1M context) --- .planning/REQUIREMENTS.md | 18 +++++++++--------- .planning/ROADMAP.md | 15 ++++++++------- .planning/STATE.md | 22 +++++++++++----------- 3 files changed, 28 insertions(+), 27 deletions(-) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 4f0e0eaa..e836cc91 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -50,10 +50,10 @@ Requirements for the Clean & Green milestone (releases as Cement 3.0.16). Each m ### Issue Backlog Triage -- [ ] **TRIAGE-01**: Open GitHub issues exported and bucketed (close-stale, close-wontfix, close-duplicate, real-bug, feature-request, question) -- [ ] **TRIAGE-02**: User-approved batch closures applied with consistent comment template explaining policy -- [ ] **TRIAGE-03**: Surviving issues labeled (`bug`, `cement-3-fix`, `cement-4-candidate`, `docs`, `help-wanted`) and prioritized -- [ ] **TRIAGE-04**: Real bugs discovered during triage either fixed in this milestone or recorded as backlog items with explicit deferral rationale +- [x] **TRIAGE-01**: Open GitHub issues exported and bucketed (close-stale, close-wontfix, close-duplicate, real-bug, feature-request, question) — Closed via manual pass (Phase 04, 2026-05-05); no formal snapshot artifact produced — maintainer reviewed in-place against the live backlog (see 04-NOTE.md) +- [x] **TRIAGE-02**: User-approved batch closures applied with consistent comment template explaining policy — Closed via manual pass (Phase 04, 2026-05-05); closure comment template recorded in 04-NOTE.md +- [x] **TRIAGE-03**: Surviving issues labeled (`bug`, `cement-3-fix`, `cement-4-candidate`, `docs`, `help-wanted`) and prioritized — Closed via manual pass (Phase 04, 2026-05-05); handled in-place by maintainer +- [x] **TRIAGE-04**: Real bugs discovered during triage either fixed in this milestone or recorded as backlog items with explicit deferral rationale — Closed via manual pass (Phase 04, 2026-05-05); handled in-place by maintainer ### Internal Refactor @@ -148,10 +148,10 @@ Populated by the roadmapper during phase mapping. | DOCS-02 | Phase 5 | Pending | | DOCS-03 | Phase 6 | Pending | | DOCS-04 | Phase 5 | Pending | -| TRIAGE-01 | Phase 4 | Pending | -| TRIAGE-02 | Phase 4 | Pending | -| TRIAGE-03 | Phase 4 | Pending | -| TRIAGE-04 | Phase 4 | Pending | +| TRIAGE-01 | Phase 4 | Closed (manual, 04-NOTE.md) | +| TRIAGE-02 | Phase 4 | Closed (manual, 04-NOTE.md) | +| TRIAGE-03 | Phase 4 | Closed (manual, 04-NOTE.md) | +| TRIAGE-04 | Phase 4 | Closed (manual, 04-NOTE.md) | | REFACTOR-01 | Phase 3 | Validated (Phase 03 Plan 08 — D-20 acceptance via 100% coverage gate) | | REFACTOR-02 | Phase 3 | Validated (Phase 03 Plan 05 — D-09 Any-tightening; 41 → 40; D-24 #6) | | REFACTOR-03 | Phase 3 | Validated (Phase 03 Plan 06) | @@ -175,4 +175,4 @@ Populated by the roadmapper during phase mapping. --- *Requirements defined: 2026-04-24* -*Last updated: 2026-04-24 after roadmap mapping* +*Last updated: 2026-05-05 after Phase 04 manual completion (TRIAGE-01..04 closed)* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 920f9d1c..2f003206 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -17,7 +17,7 @@ This roadmap delivers Cement 3.0.16, a maintenance/modernization release on the - [x] **Phase 1: Tooling Baseline & Python Matrix** - Bump ruff/mypy/pytest, drop 3.9, fix the lint/type fallout (completed 2026-04-30) - [x] **Phase 2: Dependencies & CI Pipeline** - Refresh deps, unblock the `pdm update` Action, get the matrix green (completed 2026-05-02; D-19 #1 PR-CI-green and #3 post-merge workflow_dispatch deferred to live-CI verification — see 02-VERIFICATION.md) - [x] **Phase 3: Internal Refactor & Coverage Hardening** - Cleanup-only refactor under the 100% coverage gate (completed 2026-05-04; all 9 D-24 conjuncts GREEN — see 03-VERIFICATION.md) -- [ ] **Phase 4: Backlog Triage** - Bulk-close stale issues with user approval, label and prioritize survivors +- [x] **Phase 4: Backlog Triage** - Bulk-close stale issues with user approval, label and prioritize survivors (completed 2026-05-05 via manual pass outside GSD; see 04-NOTE.md) - [ ] **Phase 5: Deprecations, Docs & Security Stubs** - Add warn-only deprecations, refresh docs, capture audit-tooling backlog - [ ] **Phase 6: Release Cut 3.0.16** - Changelog, TestPyPI smoke test, tag, GitHub release, PyPI publish, bump to 3.0.17 @@ -138,12 +138,13 @@ Plans: **Goal**: Bring the GitHub issue backlog to a known clean state via user-approved bulk triage, with surviving issues consistently labeled and any real bugs surfaced as either in-milestone fixes or explicitly deferred backlog items. **Depends on**: Phase 2 (CI green so triage decisions are not contaminated by tooling noise; can run in parallel with Phase 3) **Requirements**: TRIAGE-01, TRIAGE-02, TRIAGE-03, TRIAGE-04 +**Status**: Complete via manual pass (2026-05-05). Maintainer triaged the backlog directly against `github.com/datafolklabs/cement` outside the GSD workflow rather than producing CONTEXT/PLAN/VERIFICATION artifacts. See `.planning/phases/04-backlog-triage/04-NOTE.md` for the closure comment template used and per-requirement disposition. **Success Criteria** (what must be TRUE): - 1. A snapshot CSV/JSON of pre-triage open issues is committed to the planning artifacts and bucketed (close-stale, close-wontfix, close-duplicate, real-bug, feature-request, question) - 2. Batch closures applied to user-approved buckets carry a consistent comment template that names the policy (e.g., "closing per Cement 3.0.16 stale-issue policy") - 3. Every surviving open issue carries at least one of: `bug`, `cement-3-fix`, `cement-4-candidate`, `docs`, `help-wanted` - 4. Real bugs identified during triage are either fixed in this milestone (with PR linked) or recorded as a backlog item with explicit deferral rationale -**Plans**: TBD + 1. A snapshot CSV/JSON of pre-triage open issues is committed to the planning artifacts and bucketed (close-stale, close-wontfix, close-duplicate, real-bug, feature-request, question) — not produced; manual pass substituted + 2. Batch closures applied to user-approved buckets carry a consistent comment template that names the policy (e.g., "closing per Cement 3.0.16 stale-issue policy") — satisfied; template recorded in 04-NOTE.md + 3. Every surviving open issue carries at least one of: `bug`, `cement-3-fix`, `cement-4-candidate`, `docs`, `help-wanted` — handled in-place by maintainer during manual pass + 4. Real bugs identified during triage are either fixed in this milestone (with PR linked) or recorded as a backlog item with explicit deferral rationale — handled in-place during manual pass +**Plans**: None (manual completion) ### Phase 5: Deprecations, Docs & Security Stubs **Goal**: Land warn-only `DeprecationWarning` surfaces flagged for removal in 3.2.0 / Cement 4, refresh user-facing documentation (excluding the changelog cut, which lives in Phase 6), and record the security audit-tooling stubs as backlog items so the next milestone has a phase-shaped starting point. @@ -179,7 +180,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6. Phases 3 and 4 | 1. Tooling Baseline & Python Matrix | 4/4 | Complete | 2026-04-30 | | 2. Dependencies & CI Pipeline | 0/TBD | Not started | - | | 3. Internal Refactor & Coverage Hardening | 8/8 | Complete | 2026-05-04 | -| 4. Backlog Triage | 0/TBD | Not started | - | +| 4. Backlog Triage | manual | Complete | 2026-05-05 | | 5. Deprecations, Docs & Security Stubs | 0/TBD | Not started | - | | 6. Release Cut 3.0.16 | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 65123d0c..87325706 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,9 +3,9 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone status: completed -stopped_at: "Phase 3 COMPLETE. All 8 plans landed; all 9 D-24 conjuncts GREEN against fresh caches (defense-in-depth reset per RESEARCH.md Runtime State Inventory: make superclean && make init && make test && make comply-ruff && make comply-mypy && make audit-public-api all exit 0); REFACTOR-01..04 + COV-01..03 SATISFIED; ROADMAP marked Phase 3 [x] complete with date 2026-05-04 and 8/8 progress; 84 total Phase 3 commits on modernization-phase-3 branch. Phase 4 (Backlog Triage) and Phase 5 (Deprecations, Docs & Security Stubs) unblocked." -last_updated: "2026-05-04T05:44:36.655Z" -last_activity: 2026-05-04 -- Phase 03 marked complete +stopped_at: "Phase 4 COMPLETE via manual pass (no GSD plan artifacts produced). Maintainer triaged github.com/datafolklabs/cement backlog in-place: 80 open issues reviewed, age/inactivity closures applied with the closure-comment template recorded in 04-NOTE.md, survivors labeled in-place, real bugs handled in-place. TRIAGE-01..04 marked Closed (manual). ROADMAP marked Phase 4 [x] complete with date 2026-05-05. Phase 5 (Deprecations, Docs & Security Stubs) is the next active phase." +last_updated: "2026-05-05T00:00:00.000Z" +last_activity: 2026-05-05 -- Phase 04 marked complete (manual pass) progress: total_phases: 7 completed_phases: 4 @@ -21,14 +21,14 @@ progress: See: .planning/PROJECT.md (updated 2026-04-24) **Core value:** Cement 3 stays solid, secure, performant, and bug-free under strict backward compatibility — while being continuously maintained against a modern Python and tooling ecosystem. -**Current focus:** Phase 03 — internal-refactor-coverage-hardening +**Current focus:** Phase 05 — deprecations-docs-security-stubs (next active phase) ## Current Position -Phase: 03 — COMPLETE -Plan: 2 of 9 -Status: Phase 03 complete -Last activity: 2026-05-04 -- Phase 03 marked complete +Phase: 04 — COMPLETE (manual pass) +Plan: n/a (no GSD plans produced) +Status: Phase 04 complete via manual pass — see .planning/phases/04-backlog-triage/04-NOTE.md +Last activity: 2026-05-05 -- Phase 04 marked complete (manual pass) Progress: [██████████] 100% (21/21 plans completed across Phases 1, 01.1, 2, 3 — Phases 4-6 plan counts TBD) @@ -158,6 +158,6 @@ None yet. ## Session Continuity -Last session: 2026-05-04T04:31:51Z -Stopped at: Phase 3 COMPLETE. All 8 plans landed; all 9 D-24 conjuncts GREEN against fresh caches (defense-in-depth reset per RESEARCH.md Runtime State Inventory: make superclean && make init && make test && make comply-ruff && make comply-mypy && make audit-public-api all exit 0); REFACTOR-01..04 + COV-01..03 SATISFIED; ROADMAP marked Phase 3 [x] complete with date 2026-05-04 and 8/8 progress; 84 total Phase 3 commits on modernization-phase-3 branch. Phase 4 (Backlog Triage) and Phase 5 (Deprecations, Docs & Security Stubs) unblocked. -Resume file: None +Last session: 2026-05-05T00:00:00Z +Stopped at: Phase 4 COMPLETE via manual pass (no GSD plan artifacts produced). Maintainer triaged github.com/datafolklabs/cement backlog in-place: 80 open issues reviewed, age/inactivity closures applied with the closure-comment template recorded in 04-NOTE.md, survivors labeled in-place, real bugs handled in-place. TRIAGE-01..04 marked Closed (manual). ROADMAP marked Phase 4 [x] complete with date 2026-05-05. Phase 5 (Deprecations, Docs & Security Stubs) is the next active phase. +Resume file: .planning/phases/04-backlog-triage/04-NOTE.md From a22561e7088ff25c40627250565847423b0b15fb Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:27:58 -0500 Subject: [PATCH 02/28] docs(state): record phase 5 context session --- .planning/STATE.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.planning/STATE.md b/.planning/STATE.md index 87325706..6ef5bffd 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,9 +2,9 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone -status: completed -stopped_at: "Phase 4 COMPLETE via manual pass (no GSD plan artifacts produced). Maintainer triaged github.com/datafolklabs/cement backlog in-place: 80 open issues reviewed, age/inactivity closures applied with the closure-comment template recorded in 04-NOTE.md, survivors labeled in-place, real bugs handled in-place. TRIAGE-01..04 marked Closed (manual). ROADMAP marked Phase 4 [x] complete with date 2026-05-05. Phase 5 (Deprecations, Docs & Security Stubs) is the next active phase." -last_updated: "2026-05-05T00:00:00.000Z" +status: planning +stopped_at: Phase 5 context gathered +last_updated: "2026-05-07T19:57:50.721Z" last_activity: 2026-05-05 -- Phase 04 marked complete (manual pass) progress: total_phases: 7 @@ -158,6 +158,6 @@ None yet. ## Session Continuity -Last session: 2026-05-05T00:00:00Z -Stopped at: Phase 4 COMPLETE via manual pass (no GSD plan artifacts produced). Maintainer triaged github.com/datafolklabs/cement backlog in-place: 80 open issues reviewed, age/inactivity closures applied with the closure-comment template recorded in 04-NOTE.md, survivors labeled in-place, real bugs handled in-place. TRIAGE-01..04 marked Closed (manual). ROADMAP marked Phase 4 [x] complete with date 2026-05-05. Phase 5 (Deprecations, Docs & Security Stubs) is the next active phase. -Resume file: .planning/phases/04-backlog-triage/04-NOTE.md +Last session: 2026-05-07T19:57:50.715Z +Stopped at: Phase 5 context gathered +Resume file: .planning/phases/05-deprecations-docs-security-stubs/05-CONTEXT.md From e4744d83c6230bff426e02a7d8a608aaae363694 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:27:59 -0500 Subject: [PATCH 03/28] docs(05): create phase plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Land 6 PLAN.md files covering the 14-commit D-16 sequence from 05-CONTEXT.md, organized into 6 linearized waves (CHANGELOG.md file ownership forces serialization, matching Phase 2 precedent): - 05-01-PLAN.md (Wave 1): tighten DEPRECATIONS registry + adjacent docstring sweep across ext_logging.py and ext_smtp.py — D-16 1/2/3 - 05-02-PLAN.md (Wave 2): resolve all 4 sphinx warnings (conf.py duplicate dict, api/index.rst orphan, interface.py:102 string-quote, shell.py cmd() inline-literal RST) — D-16 5/6/7/8 - 05-03-PLAN.md (Wave 3): add top-level DEPRECATIONS.md mirroring GitBook narrative with 4 H2 blocks — D-16 4 - 05-04-PLAN.md (Wave 4): wire -W into make docs + AUDIT POINT comment — D-16 9 - 05-05-PLAN.md (Wave 5): drop Travis surfaces from README + align CONTRIBUTING with Conventional Commits + DOCS-04 fix-on-find sweep (RESEARCH.md A5 pre-verified 0 hits) — D-16 10/11/optional 12 - 05-06-PLAN.md (Wave 6): sync CONVENTIONS.md ruff target-version to py310 + expand SECv2-01..03 with phase-shaped scope notes (planning-artifact, NO CHANGELOG entries) — D-16 13/14 Plans are written prompts: every task carries with file:line anchors, with verbatim BEFORE/AFTER text from RESEARCH.md Code Examples 1-10, and with grep-verifiable conditions encoded against the bucket-per-commit table from RESEARCH.md Pitfall 7. The 8 RESEARCH.md pitfalls (esp. Pitfall 2 conf.py duplicate dict, Pitfall 5 -W flag ordering, Pitfall 6 CONVENTIONS already-mostly-done, Pitfall 7 planning- artifact filter for commits 13/14, Pitfall 8 dotted GitBook anchors) are encoded as task-level guards. Each plan includes a block per ASVS L1; the threat surface is narrow (no new code paths) and dispositions are mostly accept/mitigate against information-disclosure (stale links, anchor format) and tampering (config edits, planning-intel drift). ROADMAP.md updated: Phase 5 Plans block populated with 6 plans across 6 waves; progress table updated to 0/6. Validation: gsd-sdk frontmatter validate + verify plan-structure all return valid:true with zero errors and zero warnings on all 6 plans. Co-Authored-By: Claude Opus 4.7 (1M context) --- .planning/ROADMAP.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 2f003206..c39e172b 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -156,7 +156,32 @@ Plans: 3. `make docs` builds Sphinx docs with zero warnings and no broken cross-references; README and CONTRIBUTING walkthroughs run end-to-end against the 3.0.16 development tree without errors 4. Public API docstrings have been swept for staleness — examples that don't run are corrected or removed (a sampling round-trip on representative examples passes) 5. SEC-01/02/03 backlog items exist (issues or planning entries) with phase-shaped scope notes for `pip-audit`, `bandit`, and CodeQL/Semgrep — sufficient for a future milestone to pick up without re-discovery -**Plans**: TBD +**Plans**: 6 plans across 6 waves (linearized — CHANGELOG.md file conflicts force serial waves; matches Phase 2 precedent) + + **Wave 1** + - [ ] 05-01-PLAN.md — Tighten DEPRECATIONS registry + adjacent docstring sweep (commits 1, 2, 3 of D-16) + + **Wave 2** *(blocked on Wave 1 completion)* + - [ ] 05-02-PLAN.md — Resolve all 4 known sphinx warnings (commits 5, 6, 7, 8 of D-16) + + **Wave 3** *(blocked on Wave 2 completion)* + - [ ] 05-03-PLAN.md — Add top-level DEPRECATIONS.md mirroring GitBook narrative (commit 4 of D-16) + + **Wave 4** *(blocked on Waves 2 + 3 completion — sphinx clean is prerequisite for -W flip)* + - [ ] 05-04-PLAN.md — Wire -W into make docs + AUDIT POINT comment (commit 9 of D-16) + + **Wave 5** *(blocked on Wave 4 completion)* + - [ ] 05-05-PLAN.md — Drop Travis from README + align CONTRIBUTING with Conventional Commits + DOCS-04 sweep (commits 10, 11, optional 12 of D-16) + + **Wave 6** *(blocked on Wave 5 completion — final planning-artifact wave)* + - [ ] 05-06-PLAN.md — Sync CONVENTIONS.md ruff target-version + expand SECv2-01..03 with phase-shaped scope notes (commits 13, 14 of D-16; planning-artifact, NO CHANGELOG entries) + + **Cross-cutting constraints** *(applies to every plan)* + - 100% coverage gate must remain green after each commit (Phase 2 D-10/D-11) + - All commits follow Conventional Commits + 78-char wrap (CLAUDE.md) + - CHANGELOG.md `## 3.0.15 - DEVELOPMENT` updated phase-by-phase per CLAUDE.md (commits 13 + 14 are planning-artifact and get NO CHANGELOG entry per RESEARCH.md Pitfall 7) + - `make audit-public-api` exit 0 enforced byte-for-byte across every commit (Phase 3 D-04 / Phase 5 D-18 #3) + - `make docs` (post-Wave 4) must exit 0 with -W enabled — zero warnings (Phase 5 D-09) ### Phase 6: Release Cut 3.0.16 **Goal**: Cut the 3.0.16 release: finalize the changelog, validate the release workflow against TestPyPI, tag, publish to PyPI, and bump the dev version to 3.0.17 per odd/even convention. @@ -181,7 +206,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6. Phases 3 and 4 | 2. Dependencies & CI Pipeline | 0/TBD | Not started | - | | 3. Internal Refactor & Coverage Hardening | 8/8 | Complete | 2026-05-04 | | 4. Backlog Triage | manual | Complete | 2026-05-05 | -| 5. Deprecations, Docs & Security Stubs | 0/TBD | Not started | - | +| 5. Deprecations, Docs & Security Stubs | 0/6 | Not started | - | | 6. Release Cut 3.0.16 | 0/TBD | Not started | - | --- From a41995bbe5b33614b87809131ef3fa5d0c26d563 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:27:59 -0500 Subject: [PATCH 04/28] docs(05): record planning completion in STATE --- .planning/STATE.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.planning/STATE.md b/.planning/STATE.md index 6ef5bffd..0e386282 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,16 +2,16 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone -status: planning +status: executing stopped_at: Phase 5 context gathered -last_updated: "2026-05-07T19:57:50.721Z" -last_activity: 2026-05-05 -- Phase 04 marked complete (manual pass) +last_updated: "2026-05-07T22:26:19.533Z" +last_activity: 2026-05-07 -- Phase 05 planning complete progress: total_phases: 7 completed_phases: 4 - total_plans: 22 + total_plans: 28 completed_plans: 22 - percent: 100 + percent: 79 --- # Project State @@ -27,8 +27,8 @@ See: .planning/PROJECT.md (updated 2026-04-24) Phase: 04 — COMPLETE (manual pass) Plan: n/a (no GSD plans produced) -Status: Phase 04 complete via manual pass — see .planning/phases/04-backlog-triage/04-NOTE.md -Last activity: 2026-05-05 -- Phase 04 marked complete (manual pass) +Status: Ready to execute +Last activity: 2026-05-07 -- Phase 05 planning complete Progress: [██████████] 100% (21/21 plans completed across Phases 1, 01.1, 2, 3 — Phases 4-6 plan counts TBD) From 8c4958d677f4583b6fc865624d201b219c0e5c95 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:27:59 -0500 Subject: [PATCH 05/28] refactor(core.deprecations): tighten removal-version language MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pin 3.0.10-1 (FATAL logging) and 3.0.16-1 (SMTPMailHandler.send bool return) to v3.2.0 in DEPRECATIONS dict. Aligns with the existing 3.0.8-1 / 3.0.8-2 policy. Removal target is the next breakage-allowed minor; downstream apps that have ignored the warning since 3.0.10 have had ample time. DEPREC-01 acceptance criterion #5: every entry in cement/core/deprecations.py:DEPRECATIONS now names a removal version. DEPREC-03 already-satisfied — existing tests assert by ID, not by message text. --- CHANGELOG.md | 1 + cement/core/deprecations.py | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 971a479a..91db41f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -289,6 +289,7 @@ Refactoring: all of cement/: `grep -nE 'pragma:[[:space:]]*no[[:space:]]*cover' cement/ | grep -vE '# (<8 categories>)'` returns empty (141 sites all carry locked-vocabulary category labels). +- `[core.deprecations]` Pin 3.0.10-1 and 3.0.16-1 removal version to v3.2.0 Misc: diff --git a/cement/core/deprecations.py b/cement/core/deprecations.py index bf0d6ef4..674889fa 100644 --- a/cement/core/deprecations.py +++ b/cement/core/deprecations.py @@ -4,8 +4,8 @@ DEPRECATIONS = { '3.0.8-1': "Environment variable CEMENT_FRAMEWORK_LOGGING is deprecated in favor of CEMENT_LOG, and will be removed in Cement v3.2.0", # noqa: E501 '3.0.8-2': "App.Meta.framework_logging will be changed or removed in Cement v3.2.0", # noqa: E501 - '3.0.10-1': "The FATAL logging facility is deprecated in favor of CRITICAL, and will be removed in future versions of Cement.", # noqa: E501 - '3.0.16-1': "SMTPMailHandler.send() returning bool is deprecated. It will return the smtplib senderrs dict in a future version of Cement", # noqa: E501 + '3.0.10-1': "The FATAL logging facility is deprecated in favor of CRITICAL, and will be removed in Cement v3.2.0.", # noqa: E501 + '3.0.16-1': "SMTPMailHandler.send() returning bool is deprecated. It will return the smtplib senderrs dict in Cement v3.2.0", # noqa: E501 } From 11505c63425003c21d7a7020441c7ed29cfb4d2d Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:00 -0500 Subject: [PATCH 06/28] refactor(ext.logging): tighten FATAL deprecation removal version in docstrings Pin set_level() and fatal() docstrings to v3.2.0 (matches the 3.0.10-1 DEPRECATIONS entry tightened in the prior commit). Also fix the "us"/"use" typo and switch single-backtick CRITICAL / critical() to RST inline-literal double-backtick form so autodoc renders them as code, not emphasis. DEPREC-01 acceptance carried at the docstring layer for the load-bearing user-visible surface. --- CHANGELOG.md | 1 + cement/ext/ext_logging.py | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 91db41f0..e83c21d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -290,6 +290,7 @@ Refactoring: returns empty (141 sites all carry locked-vocabulary category labels). - `[core.deprecations]` Pin 3.0.10-1 and 3.0.16-1 removal version to v3.2.0 +- `[ext.logging]` Tighten FATAL deprecation removal version in docstrings Misc: diff --git a/cement/ext/ext_logging.py b/cement/ext/ext_logging.py index c6ff9627..1ecf90e7 100644 --- a/cement/ext/ext_logging.py +++ b/cement/ext/ext_logging.py @@ -144,7 +144,7 @@ def set_level(self, level: str) -> None: ``['INFO', 'WARNING', 'ERROR', 'DEBUG', 'FATAL', 'CRITICAL]``. As of Cement 3.0.10, the FATAL facility is deprecated and will be - removed in future versions of Cement. Please us `CRITICAL` instead. + removed in Cement v3.2.0. Please use ``CRITICAL`` instead. :param level: The log level to set. @@ -366,7 +366,7 @@ def fatal(self, msg: str, namespace: str | None = None, **kw: Any) -> None: Log to the FATAL (aka CRITICAL) facility. As of Cement 3.0.10, this method is deprecated and will be removed in - future versions of Cement. Please us `critical()` instead. + Cement v3.2.0. Please use ``critical()`` instead. Args: msg (str): The message to log. From c14f0403dc31d35a99ce3ffa76cdc0851ce015cd Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:00 -0500 Subject: [PATCH 07/28] refactor(ext.smtp): document send() bool-return removal in v3.2.0 Insert a Sphinx .. deprecated:: 3.0.16 admonition into the send() docstring between Returns and Example. Pairs with the runtime deprecate('3.0.16-1') call at line 189-190 (unchanged) so the deprecation is visible at both runtime AND in autodoc HTML. Also fix a zero-space-after-colon RST formatting bug (bool:``True`` -> bool: ``True``) in the same Returns block. DEPREC-01 acceptance carried at the docstring layer for the SMTPMailHandler.send return-type deprecation. --- CHANGELOG.md | 1 + cement/ext/ext_smtp.py | 7 ++++++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e83c21d4..b488141c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -291,6 +291,7 @@ Refactoring: category labels). - `[core.deprecations]` Pin 3.0.10-1 and 3.0.16-1 removal version to v3.2.0 - `[ext.logging]` Tighten FATAL deprecation removal version in docstrings +- `[ext.smtp]` Document send() bool-return removal in v3.2.0 Misc: diff --git a/cement/ext/ext_smtp.py b/cement/ext/ext_smtp.py index a51e1ab1..b118c3c8 100644 --- a/cement/ext/ext_smtp.py +++ b/cement/ext/ext_smtp.py @@ -138,7 +138,12 @@ def send(self, body: _BodyType, **kw: Any) -> bool: ``[ ('alt-name.ext', '/path/to/file.ext'), ...]`` Returns: - bool:``True`` if message is sent successfully, ``False`` otherwise + bool: ``True`` if message is sent successfully, ``False`` otherwise + + .. deprecated:: 3.0.16 + The ``bool`` return is deprecated and will change to the + ``smtplib`` senderrs ``dict`` in Cement v3.2.0. See + ``DEPRECATIONS['3.0.16-1']``. Example: From 7c0c03728218671c5cd403b391468731fbfbd0a9 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:00 -0500 Subject: [PATCH 08/28] docs(phase-05): update tracking after wave 1 --- .planning/ROADMAP.md | 2 +- .planning/STATE.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index c39e172b..863a0dde 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -159,7 +159,7 @@ Plans: **Plans**: 6 plans across 6 waves (linearized — CHANGELOG.md file conflicts force serial waves; matches Phase 2 precedent) **Wave 1** - - [ ] 05-01-PLAN.md — Tighten DEPRECATIONS registry + adjacent docstring sweep (commits 1, 2, 3 of D-16) + - [x] 05-01-PLAN.md — Tighten DEPRECATIONS registry + adjacent docstring sweep (commits 1, 2, 3 of D-16) **Wave 2** *(blocked on Wave 1 completion)* - [ ] 05-02-PLAN.md — Resolve all 4 known sphinx warnings (commits 5, 6, 7, 8 of D-16) diff --git a/.planning/STATE.md b/.planning/STATE.md index 0e386282..92517d96 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,8 +4,8 @@ milestone: v1.0 milestone_name: milestone status: executing stopped_at: Phase 5 context gathered -last_updated: "2026-05-07T22:26:19.533Z" -last_activity: 2026-05-07 -- Phase 05 planning complete +last_updated: "2026-05-07T22:50:07.883Z" +last_activity: 2026-05-07 -- Phase 05 execution started progress: total_phases: 7 completed_phases: 4 @@ -21,14 +21,14 @@ progress: See: .planning/PROJECT.md (updated 2026-04-24) **Core value:** Cement 3 stays solid, secure, performant, and bug-free under strict backward compatibility — while being continuously maintained against a modern Python and tooling ecosystem. -**Current focus:** Phase 05 — deprecations-docs-security-stubs (next active phase) +**Current focus:** Phase 05 — deprecations-docs-security-stubs ## Current Position -Phase: 04 — COMPLETE (manual pass) -Plan: n/a (no GSD plans produced) -Status: Ready to execute -Last activity: 2026-05-07 -- Phase 05 planning complete +Phase: 05 (deprecations-docs-security-stubs) — EXECUTING +Plan: 1 of 6 +Status: Executing Phase 05 +Last activity: 2026-05-07 -- Phase 05 execution started Progress: [██████████] 100% (21/21 plans completed across Phases 1, 01.1, 2, 3 — Phases 4-6 plan counts TBD) From 3f03b95b5a943f94cc93902996cb41b7edd4bcb6 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:01 -0500 Subject: [PATCH 09/28] docs(sphinx): drop unsupported 'logo' theme option from conf.py sphinx_rtd_theme 3.1.0 rejects 'logo' as an unsupported option. The duplicate html_theme_options dict at conf.py:51-53 silently overwrote the active dict at lines 19-33; deleting it (3 lines) restores the toc-config (collapse_navigation, navigation_depth, titles_only, etc.) AND drops the warning. DOCS-01 progress: 1 of 4 known sphinx warnings resolved. --- CHANGELOG.md | 1 + docs/source/conf.py | 3 --- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b488141c..90e7815d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -321,6 +321,7 @@ Misc: `03-VERIFICATION.md`. - `[dev]` Phase 03 (Internal Refactor & Coverage Hardening) complete: REFACTOR-01..04 + COV-01..03 satisfied; ROADMAP updated. +- `[docs]` Drop unsupported 'logo' theme option from sphinx conf Deprecations: diff --git a/docs/source/conf.py b/docs/source/conf.py index 8a3ac585..68fcbab4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,9 +48,6 @@ # ] # } # -html_theme_options = { - 'logo': 'logo-text.png', -} # html_theme_path = guzzle_sphinx_theme.html_theme_path() # html_theme = 'alabaster' From c67cfe8dae98ba41ee406bd48f6b242da6012e38 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:01 -0500 Subject: [PATCH 10/28] docs(sphinx): wire api/index into top-level toctree docs/source/api/index.rst was an orphan duplicate of the top-level docs/source/index.rst toctree (both referenced api/core/index, api/utils/index, api/ext/index). Sphinx flagged the orphan with "document isn't included in any toctree". Deleting the orphan keeps the top-level toctree as the single source of truth. Pre-flight: no external references to api/index.html in .planning/, docs/, or README.md. DOCS-01 progress: 2 of 4 known sphinx warnings resolved. --- CHANGELOG.md | 1 + docs/source/api/index.rst | 14 -------------- 2 files changed, 1 insertion(+), 14 deletions(-) delete mode 100644 docs/source/api/index.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index 90e7815d..bfde5c1b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -322,6 +322,7 @@ Misc: - `[dev]` Phase 03 (Internal Refactor & Coverage Hardening) complete: REFACTOR-01..04 + COV-01..03 satisfied; ROADMAP updated. - `[docs]` Drop unsupported 'logo' theme option from sphinx conf +- `[docs]` Wire api/index into top-level toctree Deprecations: diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst deleted file mode 100644 index 0b94fdb1..00000000 --- a/docs/source/api/index.rst +++ /dev/null @@ -1,14 +0,0 @@ - -API Reference -============================================================================== - -.. note:: This documentation is strictly for API reference. For more complete - developer documentation, please visit the official site - http://builtoncement.com. - - .. toctree:: - :maxdepth: 1 - - core/index - utils/index - ext/index From 4bde5fe24162b0c0d4c68be38ab416e04a37ceab Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:01 -0500 Subject: [PATCH 11/28] fix(core.interface): string-quote list[str] for autodoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The InterfaceManager.list method-name shadows the builtin, so autodoc's inspect.signature() introspection tries to subscript the method object (self.list, which has type function) instead of builtins.list, producing: WARNING: Failed to get a method signature for cement.core.interface.InterfaceManager.list: 'function' object is not subscriptable String-quoting the return annotation defers evaluation past the method-name binding. The local fix preserves Phase 3 D-08 (from __future__ import annotations removal stays in effect file-wide). Inline `# autodoc:` comment is grep-able for future cleanup. The sibling files (hook.py, handler.py, extension.py) use a different pattern (import builtins + builtins.list[T]) — preserved as a future consistency-cleanup candidate per RESEARCH.md Open Question 1. audit-public-api is annotation-blind (verified) — no baseline rebase needed. DOCS-01 progress: 3 of 4 known sphinx warnings resolved. --- CHANGELOG.md | 2 ++ cement/core/interface.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bfde5c1b..fee33f59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -134,6 +134,8 @@ Bugs: `OSError`). Gating runtime contracts on `AssertionError` was already fragile under `-O`, so this is a robustness fix rather than a contract regression on a load-bearing surface. +- `[core.interface]` String-quote list[str] return annotation for + autodoc compatibility Features: diff --git a/cement/core/interface.py b/cement/core/interface.py index d429d878..be71b7ff 100644 --- a/cement/core/interface.py +++ b/cement/core/interface.py @@ -99,7 +99,7 @@ def get(self, else: raise exc.InterfaceError(f"interface '{interface}' does not exist!") - def list(self) -> list[str]: + def list(self) -> "list[str]": # autodoc: PEP 585 + method-name-shadow workaround """ Return a list of defined interfaces. From 3f8999fd97e02ca9466f07b55e5f4617ddb17ae5 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:02 -0500 Subject: [PATCH 12/28] docs(sphinx): rename display_version to version_selector sphinx_rtd_theme 3.0+ renamed the `display_version` theme option to `version_selector`. The active html_theme_options dict at conf.py:19 still carried the old name; the warning was masked while the duplicate-dict overwrote the active config and only surfaced after Plan 05-02 Task 1 deleted the duplicate. This is a Rule 1/3 deviation from the Plan 05-02 task list: the 4 known sphinx warnings the plan was scoped against did NOT include this one (it became visible only after the Task 1 delete). Fixing it here is required to meet Task 4's phase-level gate precondition (`sphinx-build ... | grep -cE '(WARNING|ERROR):' returns 0`) so Plan 04 can flip `make docs` to use `-W`. DOCS-01 progress: bonus warning resolved en route to the original 4. --- CHANGELOG.md | 2 ++ docs/source/conf.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fee33f59..21217d9e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -325,6 +325,8 @@ Misc: REFACTOR-01..04 + COV-01..03 satisfied; ROADMAP updated. - `[docs]` Drop unsupported 'logo' theme option from sphinx conf - `[docs]` Wire api/index into top-level toctree +- `[docs]` Rename `display_version` theme option to `version_selector` + (sphinx_rtd_theme 3.x rename) Deprecations: diff --git a/docs/source/conf.py b/docs/source/conf.py index 68fcbab4..d1ef43b8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -20,7 +20,7 @@ 'canonical_url': '', 'analytics_id': '', 'logo_only': False, - 'display_version': True, + 'version_selector': True, 'prev_next_buttons_location': 'bottom', 'style_external_links': False, 'vcs_pageview_mode': '', From 3e9a433fdba7886d42548448f13323e96a8c3add Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:02 -0500 Subject: [PATCH 13/28] docs(utils.shell): fix inline-literal RST in cmd() docstring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The actual bug was an inline literal that spanned a line break in the source — `\`\`(stdout, stderror,⏎ return_code)\`\`` — RST inline literals must close on the same line they open. Reflowing the prose so the parenthesized literal stays on one line clears the docutils warning. The slash separator between `\`\`text=True\`\` /\`\`encoding=...\`\`` was a separate concern called out in Plan 05-02 Pitfall 3. Pitfall 3's prescribed `or` swap alone did NOT clear the warning; the line-spanning literal above it was the load-bearing fix. The slash is also replaced with `or` in the same reflow for consistency with the plan's intent. `exec_cmd()` (lines 73-91) still carries the same slash form per plan instructions (D-08 #4 names only `cmd()`); no warning fires there because its docstring keeps `\`\`(stdout, stderror, return_code)\`\`` on a single line — confirming the line-spanning literal was the actual root cause. DOCS-01 progress: 4 of 4 originally-known sphinx warnings resolved. After this commit + the version_selector rename, sphinx-build emits 0 warnings; Plan 04 (D-16 step 9) can flip `make docs` to use `-W`. --- CHANGELOG.md | 1 + cement/utils/shell.py | 10 +++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 21217d9e..73597d1f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -327,6 +327,7 @@ Misc: - `[docs]` Wire api/index into top-level toctree - `[docs]` Rename `display_version` theme option to `version_selector` (sphinx_rtd_theme 3.x rename) +- `[docs]` Fix inline-literal RST in shell.cmd() docstring Deprecations: diff --git a/cement/utils/shell.py b/cement/utils/shell.py index 48af4df7..956a33f7 100644 --- a/cement/utils/shell.py +++ b/cement/utils/shell.py @@ -32,11 +32,11 @@ def cmd(command: str, kwargs: Additional keyword arguments are passed to ``Popen()``. Returns: - tuple: When ``capture==True``, returns the ``(stdout, stderror, - return_code)`` of the command. ``stdout`` and ``stderror`` are - ``bytes`` (the ``Popen`` default); decode with the appropriate - encoding if string output is needed, or pass ``text=True`` / - ``encoding=...`` through ``**kwargs``. + tuple: When ``capture==True``, returns ``(stdout, stderror, return_code)`` + of the command. ``stdout`` and ``stderror`` are ``bytes`` (the + ``Popen`` default); decode with the appropriate encoding if string + output is needed, or pass ``text=True`` or ``encoding=...`` through + ``**kwargs``. int: When ``capture==False``, returns only the ``exitcode`` of the command. From 1c4faffe195b927683937be4c605fbac99ef6942 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:03 -0500 Subject: [PATCH 14/28] docs(phase-05): update tracking after wave 2 --- .planning/ROADMAP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 863a0dde..ddd1464c 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -162,7 +162,7 @@ Plans: - [x] 05-01-PLAN.md — Tighten DEPRECATIONS registry + adjacent docstring sweep (commits 1, 2, 3 of D-16) **Wave 2** *(blocked on Wave 1 completion)* - - [ ] 05-02-PLAN.md — Resolve all 4 known sphinx warnings (commits 5, 6, 7, 8 of D-16) + - [x] 05-02-PLAN.md — Resolve all 4 known sphinx warnings (commits 5, 6, 7, 8 of D-16) **Wave 3** *(blocked on Wave 2 completion)* - [ ] 05-03-PLAN.md — Add top-level DEPRECATIONS.md mirroring GitBook narrative (commit 4 of D-16) From 2f3423513d12faf4312126fd7ca8623d1e486dfb Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:03 -0500 Subject: [PATCH 15/28] docs: add top-level DEPRECATIONS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror the canonical GitBook deprecation narrative at docs.builtoncement.com/release-information/deprecations into a top-level repo-root markdown file (sibling of README.md, CHANGELOG.md, CONTRIBUTORS.md). Anchors use the dotted-version format (#3.0.8-1, NOT #3-0-8-1) per the runtime URL emitted by cement.core.deprecations.deprecate(). Per CONTEXT.md D-05/D-06: Sphinx is strictly API reference per docs/source/index.rst — free-form developer narrative lives on GitBook. The literal REQUIREMENTS.md DEPREC-02 wording ("a dedicated docs/source/deprecations.rst page") was authored without this docs-split context and is reinterpreted, not followed verbatim. DEPREC-02 acceptance: in-repo touchpoint with one H2 section per registry ID; per-block format = surface, since, removal, migration prose with code example, GitBook back-link. --- CHANGELOG.md | 1 + DEPRECATIONS.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 DEPRECATIONS.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 73597d1f..a3913cc3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -328,6 +328,7 @@ Misc: - `[docs]` Rename `display_version` theme option to `version_selector` (sphinx_rtd_theme 3.x rename) - `[docs]` Fix inline-literal RST in shell.cmd() docstring +- `[docs]` Add top-level DEPRECATIONS.md mirroring GitBook narrative Deprecations: diff --git a/DEPRECATIONS.md b/DEPRECATIONS.md new file mode 100644 index 00000000..8ad46574 --- /dev/null +++ b/DEPRECATIONS.md @@ -0,0 +1,84 @@ +# Cement Deprecations + +This document mirrors the canonical GitBook narrative at +[docs.builtoncement.com/release-information/deprecations](https://docs.builtoncement.com/release-information/deprecations) +for in-repo discoverability. Each deprecation has an H2 section with +its registry ID. New IDs append at the bottom under their +since-version section. + +For runtime behavior, the `cement.core.deprecations.deprecate()` +helper emits a `DeprecationWarning` whose message includes a +back-link to the corresponding GitBook anchor. + +## 3.0.8-1 + +**Surface:** Environment variable `CEMENT_FRAMEWORK_LOGGING` +**Since:** Cement 3.0.8 +**Removal:** Cement v3.2.0 + +Use `CEMENT_LOG` instead. Single-pass migration: + +```bash +# Before +export CEMENT_FRAMEWORK_LOGGING=true + +# After +export CEMENT_LOG=true +``` + +[GitBook reference](https://docs.builtoncement.com/release-information/deprecations#3.0.8-1) + +## 3.0.8-2 + +**Surface:** `App.Meta.framework_logging` +**Since:** Cement 3.0.8 +**Removal:** Cement v3.2.0 + +Will be changed or removed. Migrate to the `CEMENT_LOG` environment +variable surface (see `3.0.8-1`). + +[GitBook reference](https://docs.builtoncement.com/release-information/deprecations#3.0.8-2) + +## 3.0.10-1 + +**Surface:** `cement.ext.ext_logging.LoggingLogHandler.fatal()` / +`set_level('FATAL')` +**Since:** Cement 3.0.10 +**Removal:** Cement v3.2.0 + +Use `critical()` / `set_level('CRITICAL')` instead. + +```python +# Before +app.log.fatal('something broke') +app.log.set_level('FATAL') + +# After +app.log.critical('something broke') +app.log.set_level('CRITICAL') +``` + +[GitBook reference](https://docs.builtoncement.com/release-information/deprecations#3.0.10-1) + +## 3.0.16-1 + +**Surface:** `cement.ext.ext_smtp.SMTPMailHandler.send()` return type +**Since:** Cement 3.0.16 +**Removal:** Cement v3.2.0 + +The `bool` return value is deprecated; in v3.2.0 the method will +return the `smtplib` senderrs `dict`. + +```python +# Before (3.0.x) +ok = app.mail.send('hello') +if not ok: + handle_error() + +# After (3.2.0+) +errs = app.mail.send('hello') +if errs: + handle_error_per_recipient(errs) +``` + +[GitBook reference](https://docs.builtoncement.com/release-information/deprecations#3.0.16-1) From c6800352bb00e6a22fffaa51edba3198b4269c50 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:03 -0500 Subject: [PATCH 16/28] docs(phase-05): update tracking after wave 3 --- .planning/ROADMAP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index ddd1464c..3fe0342b 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -165,7 +165,7 @@ Plans: - [x] 05-02-PLAN.md — Resolve all 4 known sphinx warnings (commits 5, 6, 7, 8 of D-16) **Wave 3** *(blocked on Wave 2 completion)* - - [ ] 05-03-PLAN.md — Add top-level DEPRECATIONS.md mirroring GitBook narrative (commit 4 of D-16) + - [x] 05-03-PLAN.md — Add top-level DEPRECATIONS.md mirroring GitBook narrative (commit 4 of D-16) **Wave 4** *(blocked on Waves 2 + 3 completion — sphinx clean is prerequisite for -W flip)* - [ ] 05-04-PLAN.md — Wire -W into make docs + AUDIT POINT comment (commit 9 of D-16) From 33c61eb922052e54980fc6db76c6fbfc1ac1fde1 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:04 -0500 Subject: [PATCH 17/28] chore(make): wire -W into make docs (zero-warnings gate) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Flip the docs target from `sphinx-build ./source ./build` to `sphinx-build -W ./source ./build` so future warnings fail-fast. Plan 02 (D-16 steps 5-8) resolved all 4 known warnings — this commit makes that posture enforced, not aspirational. AUDIT POINT comment matches the established convention: Phase 1 D-08 (ruff family AUDIT POINT in pyproject.toml), Phase 2 D-10/D-11 (coverage gate AUDIT POINT), Phase 3 D-06 (UP+FA family AUDIT POINT). The grep `grep -nE 'AUDIT POINT' Makefile pyproject.toml` now lists every deliberate-configuration site across the repo. DOCS-01 acceptance: make docs exits 0 with -W enabled — zero warnings, no broken cross-references. Note: -W is local-only this phase. CI integration of `make docs` is deferred to a future milestone (CONTEXT.md ). --- CHANGELOG.md | 1 + Makefile | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a3913cc3..5c616a8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -329,6 +329,7 @@ Misc: (sphinx_rtd_theme 3.x rename) - `[docs]` Fix inline-literal RST in shell.cmd() docstring - `[docs]` Add top-level DEPRECATIONS.md mirroring GitBook narrative +- `[dev]` Wire -W into make docs (zero-warnings gate) Deprecations: diff --git a/Makefile b/Makefile index 919add31..860d81a7 100644 --- a/Makefile +++ b/Makefile @@ -60,7 +60,11 @@ commit: pdm run cz commit docs: - cd docs; pdm run sphinx-build ./source ./build; cd .. + # AUDIT POINT (Phase 5 D-09): -W enforces zero docs warnings. + # If a future warning is acceptable, suppress it explicitly via + # conf.py suppress_warnings rather than reverting -W. Mirrors + # Phase 1 D-08 / Phase 2 D-10/D-11 (no implicit drift). + cd docs; pdm run sphinx-build -W ./source ./build; cd .. @echo @echo DOC: "file://"$$(echo `pwd`/docs/build/html/index.html) @echo From 015b9235ddd6f861c12066a835f9aea71d7402b5 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:04 -0500 Subject: [PATCH 18/28] docs(phase-05): update tracking after wave 4 --- .planning/ROADMAP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 3fe0342b..ae4bc251 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -168,7 +168,7 @@ Plans: - [x] 05-03-PLAN.md — Add top-level DEPRECATIONS.md mirroring GitBook narrative (commit 4 of D-16) **Wave 4** *(blocked on Waves 2 + 3 completion — sphinx clean is prerequisite for -W flip)* - - [ ] 05-04-PLAN.md — Wire -W into make docs + AUDIT POINT comment (commit 9 of D-16) + - [x] 05-04-PLAN.md — Wire -W into make docs + AUDIT POINT comment (commit 9 of D-16) **Wave 5** *(blocked on Wave 4 completion)* - [ ] 05-05-PLAN.md — Drop Travis from README + align CONTRIBUTING with Conventional Commits + DOCS-04 sweep (commits 10, 11, optional 12 of D-16) From 81f3e67ced943208fc6df83e6a79bb75f3ab31ed Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:04 -0500 Subject: [PATCH 19/28] docs(readme): drop Travis CI link (moved to GitHub Actions) Travis CI was retired in Phase 1 (.travis.yml deleted, CI moved to GitHub Actions). The README still carried two stale references: the build-status badge at line 5 (app.travis-ci.com) and a More Information list-item link at line 60 (travis-ci.org). Both deleted. The remaining badges and link list are unchanged. DOCS-02 acceptance: README is accurate against the 3.0.16 release. --- CHANGELOG.md | 1 + README.md | 2 -- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c616a8d..9b2ccbd6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -330,6 +330,7 @@ Misc: - `[docs]` Fix inline-literal RST in shell.cmd() docstring - `[docs]` Add top-level DEPRECATIONS.md mirroring GitBook narrative - `[dev]` Wire -W into make docs (zero-warnings gate) +- `[docs]` Drop Travis CI link/badge (CI moved to GitHub Actions) Deprecations: diff --git a/README.md b/README.md index d6ccd5b1..f4e5a0cc 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,6 @@ [![Built on Cement™](https://img.shields.io/badge/Built%20on%20Cement%E2%84%A2-3.0-yellow)](https://builtoncement.com) [![PyPi Downloads](https://img.shields.io/pypi/dm/cement)](https://pypistats.org/packages/cement) -[![Continuous Integration Status](https://app.travis-ci.com/datafolklabs/cement.svg?branch=master)](https://app.travis-ci.com/github/datafolklabs/cement/) Cement is an advanced Application Framework for Python, with a primary focus on Command Line Interfaces (CLI). Its goal is to introduce a standard and feature-full platform for both simple and complex command line applications as well as support rapid development needs without sacrificing quality. Cement is flexible, and its use cases span from the simplicity of a micro-framework to the complexity of a mega-framework. Whether it's a single file script or a multi-tier application, Cement is the foundation you've been looking for. @@ -57,7 +56,6 @@ See: [https://docs.builtoncement.com/extensions](https://docs.builtoncement.com/ - [Official Website / Developer Documentation](http://builtoncement.com/) - [PyPi Packages](http://pypi.python.org/pypi/cement/) - [Github Source Code / Issue Tracking](http://github.com/datafolklabs/cement/) -- [Travis CI](https://travis-ci.org/datafolklabs/cement/) - [Slack Channel](https://join.slack.com/t/cementframework/shared_invite/enQtMzU0OTc5MDQ4NDA0LWMwMzZiOTczZjM4ZjFiZDE3MDk4MzA5ZmYxNmZjNTk4NzUwMzcyN2VlMDc5NzIxYjQ1NzlmNzgyNDFjMWJmMWY) From ba46c32abdfb8a9d7100189025fb5c8afe83b885 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:05 -0500 Subject: [PATCH 20/28] docs(contributing): align with Conventional Commits + atomic-per-concern Replace "A single commit per issue" with the project's actual current discipline: atomic per concern + Conventional Commits + 78-char wrap + `make commit` (cz). Add a Commit Conventions subsection with subject/body/type/authoring rules and a back-link to CLAUDE.md as the canonical commit-shape doc. The "A single commit per issue" guidance was the inverse of how Phases 1, 2, and 3 actually shipped (84 atomic commits in Phase 3 alone) and would have given external contributors the wrong forward-looking signal. Existing reference-link block (PEP8, issue tracker, etc.) is preserved; [Conventional Commits] target appended to the block. DOCS-02 acceptance: CONTRIBUTING aligns with the 3.0.16 release discipline. --- .github/CONTRIBUTING.md | 73 ++++++++++++++++++++--------------------- CHANGELOG.md | 2 ++ 2 files changed, 37 insertions(+), 38 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index bc2ff449..b9d78690 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -35,51 +35,48 @@ The ideal feature request would include: All contributors should attempt to abide by the following: - Contributors fork the project on GitHub onto their own account -- All changes should be commited, and pushed to their repository -- All pull requests are from a topic branch, not an existing Cement branch +- All changes should be committed and pushed to their repository +- All pull requests are from a topic branch, not an existing Cement + branch - Contributors make every effort to comply with [PEP8] -- Before starting on a new feature, or bug fix, always do the following: +- Before starting on a new feature or bug fix, do the following: - `git pull --rebase` to get latest changes from upstream - - Checkout a new branch. For example: + - Checkout a new branch. For example: - `git checkout -b feature/slug-name` - `git checkout -b bug/github-issue-number` - Code must include the following: - - All tests pass successfully - - Coverage reports 100% code coverage when running tests - - New features are documented in the appropriate section of the doc - - Significant changes are mentioned in the ChangeLog -- All contributions must be associated with at least one issue in GitHub. If the issue does not exist, create one (per the guidelines above). -- Commit comments must include something like the following: - - Resolves Issue #1127 - - Partially Resolves Issue #9873 -- A single commit per issue. -- Contributors should add their full name, or handle, to the CONTRIBUTORS file. - -Regarding git commit messages, please read the following: - -* [Commit Guidelines] - -The majority of commits only require a single line commit message. That said, for more complex commits, please use the following as an example (as outlined in the ProGit link above): - -``` -Short (50 chars or less) summary of changes - -More detailed explanatory text, if necessary. Wrap it to about 72 -characters or so. In some contexts, the first line is treated as the -subject of an email and the rest of the text as the body. The blank -line separating the summary from the body is critical (unless you omit -the body entirely); tools like rebase can get confused if you run the -two together. - -Further paragraphs come after blank lines. - - - Bullet points are okay, too - - - Typically a hyphen or asterisk is used for the bullet, preceded by a - single space, with blank lines in between, but conventions vary here -``` + - All tests pass successfully (`make test`) + - Coverage reports 100% code coverage (`make test`) + - Compliance passes (`make comply` — runs `ruff` and `mypy`) + - New features are documented in the appropriate API docstring + - User-visible changes are recorded in `CHANGELOG.md` under the + active development section, in one of the standard buckets + (`Bugs`, `Features`, `Refactoring`, `Misc`, `Deprecations`) +- All contributions should be associated with at least one issue in + GitHub. If the issue does not exist, create one (per the + guidelines above). +- Contributors should add their full name or handle to the + `CONTRIBUTORS` file. + +### Commit Conventions + +Cement follows [Conventional Commits] for all commit messages. +Commits are atomic per concern — one logical change per commit, not +"a single commit per issue" (which often lumps unrelated edits). + +- **Subject line:** `(): ` + (max 78 chars) +- **Type:** `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `ci` +- **Body:** wrap at 78 chars; explain the *why*, not just the *what* +- **Authoring:** Run `make commit` to use the project's + `commitizen` (`cz`) interactive prompt. It enforces the format and + the wrap. + +See [`CLAUDE.md`](../CLAUDE.md) §"Commit Conventions" for the +canonical commit-shape doc. [Open Source Initiative]: http://www.opensource.org [issue tracker]: http://github.com/datafolklabs/cement/issues [PEP8]: http://www.python.org/dev/peps/pep-0008/ [Commit Guidelines]: http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines +[Conventional Commits]: https://www.conventionalcommits.org/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b2ccbd6..c200b197 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -331,6 +331,8 @@ Misc: - `[docs]` Add top-level DEPRECATIONS.md mirroring GitBook narrative - `[dev]` Wire -W into make docs (zero-warnings gate) - `[docs]` Drop Travis CI link/badge (CI moved to GitHub Actions) +- `[docs]` Align CONTRIBUTING with Conventional Commits + + atomic-per-concern Deprecations: From 3d7609d8226d0b9dc26c52283e9feeae4337c428 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:05 -0500 Subject: [PATCH 21/28] docs(phase-05): update tracking after wave 5 --- .planning/ROADMAP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index ae4bc251..75eec15f 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -171,7 +171,7 @@ Plans: - [x] 05-04-PLAN.md — Wire -W into make docs + AUDIT POINT comment (commit 9 of D-16) **Wave 5** *(blocked on Wave 4 completion)* - - [ ] 05-05-PLAN.md — Drop Travis from README + align CONTRIBUTING with Conventional Commits + DOCS-04 sweep (commits 10, 11, optional 12 of D-16) + - [x] 05-05-PLAN.md — Drop Travis from README + align CONTRIBUTING with Conventional Commits + DOCS-04 sweep (commits 10, 11, optional 12 of D-16) **Wave 6** *(blocked on Wave 5 completion — final planning-artifact wave)* - [ ] 05-06-PLAN.md — Sync CONVENTIONS.md ruff target-version + expand SECv2-01..03 with phase-shaped scope notes (commits 13, 14 of D-16; planning-artifact, NO CHANGELOG entries) From 3e388dd1ff550b374caeb70a5ae59ced7e34ac6c Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:05 -0500 Subject: [PATCH 22/28] docs(05): expand SECv2-01..03 with phase-shaped scope notes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expand SECv2-01 (pip-audit), SECv2-02 (bandit), SECv2-03 (SAST) with phase-shaped scope notes per D-14: Tool, Make target, CI placement, Config-file shape, New dev-dep, Exit behavior, Anchor. Closes SEC-01, SEC-02, SEC-03 — the next security-tooling milestone has a phase-shaped starting point and does not need to re-discover. SECv2-04 (SECURITY.md / disclosure process) stays as a one-liner per D-13 — distinct concern, separate future-milestone work. Planning-artifact commit per CLAUDE.md "Changelog Maintenance" filter (no user-visible surface) — no CHANGELOG entry. --- .planning/REQUIREMENTS.md | 47 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index e836cc91..ebdd2906 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -89,8 +89,55 @@ Deferred to a later milestone (likely the 3.2.0 breakage-allowed cycle or a dedi ### Security Audit Tooling Implementation - **SECv2-01**: `pip-audit` integrated into CI on every PR + - **Tool:** `pdm run pip-audit` (read deps from `pdm.lock`) + - **Make target:** `make audit-deps` — independent target, NOT + chained into `make test` or `make comply` (matches Phase 03 + D-03 `audit-public-api` discipline) + - **CI placement:** new dedicated workflow file + `.github/workflows/security.yml`, triggers on `pull_request` + + weekly `cron`. NOT serialized into `build_and_test.yml` + (mirrors Phase 02 D-16 fail-fast vs feedback-time tradeoff) + - **Config:** none initially; `pip-audit --skip` for accepted + CVEs documented inline if any surface + - **New dev-dep:** `pip-audit` (PyPI; latest stable) + - **Exit behavior:** advisory on first run (Phase 02 D-03 + one-shot precedent — capture accepted CVEs in an in-repo + artifact mirroring `02-PIP-AUDIT.md`); flip to blocking once + baseline is clean + - **Anchor:** `.planning/phases/02-dependencies-ci-pipeline/02-CONTEXT.md` + D-03 + `02-PIP-AUDIT.md` capture artifact + - **SECv2-02**: `bandit` integrated into CI on every PR with project-tuned ruleset + - **Tool:** `pdm run bandit -r cement/` + - **Make target:** `make audit-bandit` — independent target + - **CI placement:** same `.github/workflows/security.yml` lane + as SECv2-01 (one workflow, three jobs) + - **Config:** `.bandit` allowlist file at repo root — + project-tuned to skip false positives on framework-intentional + patterns (e.g., `subprocess` call sites in `cement/utils/shell.py` + that are deliberate per the public API contract) + - **New dev-dep:** `bandit` (PyPI; latest stable) + - **Exit behavior:** advisory on first run; flip to blocking + once `.bandit` allowlist is curated + - **Anchor:** `02-CONTEXT.md` D-03 (same one-shot precedent) + - **SECv2-03**: SAST tool (CodeQL or Semgrep) selected and integrated into CI + - **Tool:** TBD per evaluation; candidates are CodeQL (GitHub- + native, free for public repos, deeper Python rules) and + Semgrep (rule customization, more permissive licensing) + - **Make target:** `make audit-sast` (only if CLI-runnable; + CodeQL is GitHub-Actions-only) + - **CI placement:** dedicated job in `security.yml`; weekly + cron preferred over per-PR (run-time cost) + - **Config:** `.semgrep.yml` (Semgrep) OR + `.github/codeql/codeql-config.yml` (CodeQL) — rule selection + pinned to Python OWASP top-N + cement-specific patterns + - **New dev-dep:** `semgrep` if Semgrep selected; none if + CodeQL (GitHub-hosted) + - **Exit behavior:** advisory on first run; per-finding triage + before any blocking flip + - **Anchor:** `02-CONTEXT.md` D-03 + - **SECv2-04**: Documented security disclosure process (`SECURITY.md`) ### Performance Pass From 55619d135a9873bf05d981c8baff42e6443e1d7c Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:06 -0500 Subject: [PATCH 23/28] docs(phase-05): update tracking after wave 6 --- .planning/ROADMAP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 75eec15f..abf40e42 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -174,7 +174,7 @@ Plans: - [x] 05-05-PLAN.md — Drop Travis from README + align CONTRIBUTING with Conventional Commits + DOCS-04 sweep (commits 10, 11, optional 12 of D-16) **Wave 6** *(blocked on Wave 5 completion — final planning-artifact wave)* - - [ ] 05-06-PLAN.md — Sync CONVENTIONS.md ruff target-version + expand SECv2-01..03 with phase-shaped scope notes (commits 13, 14 of D-16; planning-artifact, NO CHANGELOG entries) + - [x] 05-06-PLAN.md — Sync CONVENTIONS.md ruff target-version + expand SECv2-01..03 with phase-shaped scope notes (commits 13, 14 of D-16; planning-artifact, NO CHANGELOG entries) **Cross-cutting constraints** *(applies to every plan)* - 100% coverage gate must remain green after each commit (Phase 2 D-10/D-11) From da814ef85f74decf251559347afd7f98a647d439 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:06 -0500 Subject: [PATCH 24/28] fix(core.deprecations): drop trailing period from 3.0.10-1 message `deprecate()` appends ". See: ..." to each entry, so a trailing period in the dict value renders as ".. See" in the runtime DeprecationWarning. The other three entries follow the implicit no-trailing-period invariant; align 3.0.10-1 with them. Tests assert ID substring presence, not message text, so this fix is safe under DEPREC-03. Surfaces from 05-REVIEW.md CR-01 (was CR-02 in the report; renumbered during commit-shaping). --- cement/core/deprecations.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cement/core/deprecations.py b/cement/core/deprecations.py index 674889fa..dac43417 100644 --- a/cement/core/deprecations.py +++ b/cement/core/deprecations.py @@ -4,7 +4,7 @@ DEPRECATIONS = { '3.0.8-1': "Environment variable CEMENT_FRAMEWORK_LOGGING is deprecated in favor of CEMENT_LOG, and will be removed in Cement v3.2.0", # noqa: E501 '3.0.8-2': "App.Meta.framework_logging will be changed or removed in Cement v3.2.0", # noqa: E501 - '3.0.10-1': "The FATAL logging facility is deprecated in favor of CRITICAL, and will be removed in Cement v3.2.0.", # noqa: E501 + '3.0.10-1': "The FATAL logging facility is deprecated in favor of CRITICAL, and will be removed in Cement v3.2.0", # noqa: E501 '3.0.16-1': "SMTPMailHandler.send() returning bool is deprecated. It will return the smtplib senderrs dict in Cement v3.2.0", # noqa: E501 } From 55f9f44a914e64632c9aa5d9ed977b7a266d04ec Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:07 -0500 Subject: [PATCH 25/28] fix(make): make docs -W gate must use && (not ;) to enforce warnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previous recipe `cd docs; pdm run sphinx-build -W ...; cd ..` chained with semicolons, so the recipe's exit code is the trailing `cd ..` (always 0). The -W flag emitted "build finished with problems" but make returned success — the zero-warnings gate Plan 04 installed was non-functional. Switched `;` to `&&` and dropped the trailing `cd ..` (Make starts a fresh shell per recipe line, so the `cd ..` was dead either way). Empirically verified: deliberately-injected sphinx warning now returns `make: *** [Makefile:67: docs] Error 1` instead of exit 0. Clean baseline still passes (no warnings, exit 0). Surfaces from 05-REVIEW.md CR-01. --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 860d81a7..3fb3e14f 100644 --- a/Makefile +++ b/Makefile @@ -64,7 +64,7 @@ docs: # If a future warning is acceptable, suppress it explicitly via # conf.py suppress_warnings rather than reverting -W. Mirrors # Phase 1 D-08 / Phase 2 D-10/D-11 (no implicit drift). - cd docs; pdm run sphinx-build -W ./source ./build; cd .. + cd docs && pdm run sphinx-build -W ./source ./build @echo @echo DOC: "file://"$$(echo `pwd`/docs/build/html/index.html) @echo From b5a8a2a20f74aec993e9d0f98963f1eae5ad68da Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:07 -0500 Subject: [PATCH 26/28] docs(changelog): record CR-01/CR-02 fixes from phase 5 review Two atomic fixes from 05-REVIEW.md (commits c4a08c34, 73ca4c73) land as user-facing bug fixes in the active 3.0.15 development section: - core.deprecations: trailing period stripped from 3.0.10-1 - dev: make docs && (was ;) so the -W gate actually fails --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c200b197..6d11b3a2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -136,6 +136,14 @@ Bugs: rather than a contract regression on a load-bearing surface. - `[core.interface]` String-quote list[str] return annotation for autodoc compatibility +- `[core.deprecations]` Drop trailing period from the `3.0.10-1` + deprecation message — `deprecate()` appends `". See: ..."`, so a + pre-existing trailing period rendered as `..` in the runtime + warning. The other three entries already follow the implicit + no-trailing-period invariant +- `[dev]` `make docs` zero-warnings gate now uses `&&` (was `;`), + so the recipe correctly fails on Sphinx warnings instead of + silently succeeding via the trailing `cd ..` exit code Features: From 05ec3b59b1ce065f5cda94fb0ae0cfc50f364d9a Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:07 -0500 Subject: [PATCH 27/28] docs(phase-05): complete phase execution --- .planning/STATE.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/.planning/STATE.md b/.planning/STATE.md index 92517d96..34d3dbf0 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,14 +4,14 @@ milestone: v1.0 milestone_name: milestone status: executing stopped_at: Phase 5 context gathered -last_updated: "2026-05-07T22:50:07.883Z" -last_activity: 2026-05-07 -- Phase 05 execution started +last_updated: "2026-05-08T00:20:22.717Z" +last_activity: 2026-05-08 progress: total_phases: 7 - completed_phases: 4 + completed_phases: 5 total_plans: 28 - completed_plans: 22 - percent: 79 + completed_plans: 28 + percent: 100 --- # Project State @@ -25,10 +25,10 @@ See: .planning/PROJECT.md (updated 2026-04-24) ## Current Position -Phase: 05 (deprecations-docs-security-stubs) — EXECUTING -Plan: 1 of 6 +Phase: 6 +Plan: Not started Status: Executing Phase 05 -Last activity: 2026-05-07 -- Phase 05 execution started +Last activity: 2026-05-08 Progress: [██████████] 100% (21/21 plans completed across Phases 1, 01.1, 2, 3 — Phases 4-6 plan counts TBD) @@ -36,7 +36,7 @@ Progress: [██████████] 100% (21/21 plans completed across Ph **Velocity:** -- Total plans completed: 6 +- Total plans completed: 12 - Average duration: — - Total execution time: 0 hours @@ -46,6 +46,7 @@ Progress: [██████████] 100% (21/21 plans completed across Ph |-------|-------|-------|----------| | 01 | 4 | - | - | | 01.1 | 1 | - | - | +| 05 | 6 | - | - | **Recent Trend:** From fca6c723a22c95d9ffb23df9d7033aa77992fda9 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Thu, 7 May 2026 19:28:08 -0500 Subject: [PATCH 28/28] docs(phase-05): evolve PROJECT.md after phase completion --- .planning/PROJECT.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index 7b2987c5..1125aaaf 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -40,11 +40,11 @@ Cement is a mature, extensible Python CLI application framework built around a h - [ ] **CI pipeline green**: all matrix jobs passing across supported Python versions; PDM auto-update resumes without drowning in lint - [x] **Python 3.9 dropped per EOL policy**: floor raised to 3.10; Python matrix = 3.10–3.14 — Validated in Phase 01 - [ ] **Test coverage held at 100%**: every change lands with tests; coverage gate remains absolute -- [ ] **Docs build healthy**: Sphinx builds cleanly; no broken refs; contributor docs accurate +- [x] **Docs build healthy**: Sphinx builds cleanly; no broken refs; contributor docs accurate — Validated in Phase 05 (4+1 warnings cleared; `make docs -W` enforces zero-warnings; CONTRIBUTING aligned with Conventional Commits) - [ ] **GitHub issue backlog triaged**: batch close stale/wontfix/duplicate with user approval; label survivors; spin real bugs into fix-phases - [ ] **Internal-only refactor**: dead code removed, type hints tightened, modern stdlib idioms (pathlib, contextlib helpers, `cached_property`) — no public API changes, no architectural shifts. Cement 4 is unscoped and stays that way during this milestone. -- [ ] **Deprecation warnings added (warn-only)**: surfaces emit `DeprecationWarning` now; actual removals are scheduled for 3.2.0 -- [ ] **Audit-tooling stub**: backlog item captured for pip-audit / bandit / SAST — spec'd but not implemented this milestone +- [x] **Deprecation warnings added (warn-only)**: surfaces emit `DeprecationWarning` now; actual removals are scheduled for 3.2.0 — Validated in Phase 05 (DEPRECATIONS dict pinned to v3.2.0; repo-root `DEPRECATIONS.md` added; runtime warning formatting fixed) +- [x] **Audit-tooling stub**: backlog item captured for pip-audit / bandit / SAST — spec'd but not implemented this milestone — Validated in Phase 05 (REQUIREMENTS.md SECv2-01..03 expanded with phase-shaped scope notes) - [ ] **Release cut: Cement 3.0.16**: tagged release, changelog, PyPI publish ### Out of Scope @@ -118,4 +118,4 @@ This document evolves at phase transitions and milestone boundaries. 4. Update Context with current state --- -*Last updated: 2026-04-30 after Phase 01 completion (tooling-baseline-python-matrix)* +*Last updated: 2026-05-08 after Phase 05 completion (deprecations-docs-security-stubs)*