feat(milestone-1): phase 5 — deprecations, docs hygiene, security stubs#776
Closed
derks wants to merge 28 commits into
Closed
feat(milestone-1): phase 5 — deprecations, docs hygiene, security stubs#776derks wants to merge 28 commits into
derks wants to merge 28 commits into
Conversation
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) <noreply@anthropic.com>
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 <read_first> with file:line anchors, <action> with verbatim BEFORE/AFTER text from RESEARCH.md Code Examples 1-10, and <acceptance_criteria> 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 <threat_model> 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) <noreply@anthropic.com>
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.
…ocstrings 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.
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.
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.
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.
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.
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.
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`.
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.
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 <deferred>).
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.
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.
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.
`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).
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.
📝 WalkthroughWalkthroughThis PR completes Phase 5 of Cement 3.0.16 by documenting and wiring deprecation metadata, enforcement of zero-warning documentation builds, expanding contributor guidelines, and updating project tracking to reflect Phase 5 execution status. ChangesPhase 5: Deprecations, Docs & Security Stubs
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/CONTRIBUTING.md:
- Line 81: Remove the unused Markdown link reference definition "[Commit
Guidelines]:
http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines"
from the CONTRIBUTING.md content; locate the literal link definition string and
delete that line so the orphan reference is eliminated and the MD053
markdownlint warning is resolved.
In @.planning/ROADMAP.md:
- Line 209: The ROADMAP.md Phase 5 table row "5. Deprecations, Docs & Security
Stubs | 0/6 | Not started | -" is inconsistent with PROJECT.md and STATE.md
which mark Phase 05 complete; update the Phase 5 row in ROADMAP.md to show the
correct progress (e.g., "6/6"), change status to "Completed" (or "Done"), and
replace the "-" with the completion date "2026-05-08" (or equivalent
verification note) so the table aligns with PROJECT.md and STATE.md.
In `@cement/utils/shell.py`:
- Around line 35-36: Docstrings in the shell utilities still misspell stderr as
"stderror"; update the return-type tuple and prose in the function docstring
(the one showing "tuple: When ``capture==True``, returns ``(stdout, stderror,
return_code)``" and the following description) to use "stderr" consistently, and
make the same correction in the exec_cmd docstring (search for "exec_cmd" and
fix any "stderror" occurrences to "stderr"); ensure the example variable names
and prose all match "stderr".
In `@CHANGELOG.md`:
- Line 335: Update the changelog entry on line 335 to accurately describe the
change: replace the incorrect "[docs] Wire api/index into top-level toctree"
with a message reflecting removal of the orphan file (for example "[docs] Remove
orphan api/index.rst; reference api/core/index, api/utils/index, api/ext/index
directly in docs/source/index.rst"). Ensure the new entry mentions deletion of
api/index.rst and that docs/source/index.rst now references the api
subdirectories directly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b3717264-7e54-442b-aabc-3b84c043e879
📒 Files selected for processing (16)
.github/CONTRIBUTING.md.planning/PROJECT.md.planning/REQUIREMENTS.md.planning/ROADMAP.md.planning/STATE.mdCHANGELOG.mdDEPRECATIONS.mdMakefileREADME.mdcement/core/deprecations.pycement/core/interface.pycement/ext/ext_logging.pycement/ext/ext_smtp.pycement/utils/shell.pydocs/source/api/index.rstdocs/source/conf.py
💤 Files with no reviewable changes (2)
- README.md
- docs/source/api/index.rst
| [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 |
There was a problem hiding this comment.
Unused link reference definition [Commit Guidelines].
The old [Commit Guidelines] reference was rendered obsolete when the commit guidance was replaced by the Conventional Commits section, but the definition was not removed. This will trigger a markdownlint MD053 warning.
✏️ Proposed fix
[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/📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| [Commit Guidelines]: http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines | |
| [PEP8]: http://www.python.org/dev/peps/pep-0008/ | |
| [Conventional Commits]: https://www.conventionalcommits.org/ |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 81-81: Link and image reference definitions should be needed
Unused link or image reference definition: "commit guidelines"
(MD053, link-image-reference-definitions)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/CONTRIBUTING.md at line 81, Remove the unused Markdown link
reference definition "[Commit Guidelines]:
http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines"
from the CONTRIBUTING.md content; locate the literal link definition string and
delete that line so the orphan reference is eliminated and the MD053
markdownlint warning is resolved.
| | 4. Backlog Triage | 0/TBD | Not started | - | | ||
| | 5. Deprecations, Docs & Security Stubs | 0/TBD | Not started | - | | ||
| | 4. Backlog Triage | manual | Complete | 2026-05-05 | | ||
| | 5. Deprecations, Docs & Security Stubs | 0/6 | Not started | - | |
There was a problem hiding this comment.
Phase 5 progress appears inconsistent with PR completion status.
The Progress table shows Phase 5 as "Not started" with 0/6 plans, but the PR summary states "12/12 must-haves passed" and "Six plans executed across six waves with verification reporting." Additionally, .planning/PROJECT.md and .planning/STATE.md both mark Phase 05 as completed on 2026-05-08.
📊 Proposed fix to align progress table with actual completion
-| 5. Deprecations, Docs & Security Stubs | 0/6 | Not started | - |
+| 5. Deprecations, Docs & Security Stubs | 6/6 | Complete | 2026-05-08 |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | 5. Deprecations, Docs & Security Stubs | 0/6 | Not started | - | | |
| | 5. Deprecations, Docs & Security Stubs | 6/6 | Complete | 2026-05-08 | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/ROADMAP.md at line 209, The ROADMAP.md Phase 5 table row "5.
Deprecations, Docs & Security Stubs | 0/6 | Not started | -" is inconsistent
with PROJECT.md and STATE.md which mark Phase 05 complete; update the Phase 5
row in ROADMAP.md to show the correct progress (e.g., "6/6"), change status to
"Completed" (or "Done"), and replace the "-" with the completion date
"2026-05-08" (or equivalent verification note) so the table aligns with
PROJECT.md and STATE.md.
Comment on lines
+35
to
+36
| tuple: When ``capture==True``, returns ``(stdout, stderror, return_code)`` | ||
| of the command. ``stdout`` and ``stderror`` are ``bytes`` (the |
There was a problem hiding this comment.
stderror misspelling persists in updated docstring.
Lines 35–36 still read stderror in both the tuple signature and the prose description. The example at line 50 (and the variable name at line 62) correctly uses stderr, so the docstring is inconsistent. The same misspelling exists in exec_cmd's unchanged docstring at line 87.
✏️ Proposed fix
- tuple: When ``capture==True``, returns ``(stdout, stderror, return_code)``
- of the command. ``stdout`` and ``stderror`` are ``bytes`` (the
+ tuple: When ``capture==True``, returns ``(stdout, stderr, return_code)``
+ of the command. ``stdout`` and ``stderr`` are ``bytes`` (theAnd in exec_cmd (line 87, outside this diff):
- tuple: The ``(stdout, stderror, return_code)`` of the command.
- ``stdout`` and ``stderror`` are ``bytes`` (the ``Popen``
+ tuple: The ``(stdout, stderr, return_code)`` of the command.
+ ``stdout`` and ``stderr`` are ``bytes`` (the ``Popen``📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| tuple: When ``capture==True``, returns ``(stdout, stderror, return_code)`` | |
| of the command. ``stdout`` and ``stderror`` are ``bytes`` (the | |
| tuple: When ``capture==True``, returns ``(stdout, stderr, return_code)`` | |
| of the command. ``stdout`` and ``stderr`` are ``bytes`` (the |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@cement/utils/shell.py` around lines 35 - 36, Docstrings in the shell
utilities still misspell stderr as "stderror"; update the return-type tuple and
prose in the function docstring (the one showing "tuple: When ``capture==True``,
returns ``(stdout, stderror, return_code)``" and the following description) to
use "stderr" consistently, and make the same correction in the exec_cmd
docstring (search for "exec_cmd" and fix any "stderror" occurrences to
"stderr"); ensure the example variable names and prose all match "stderr".
| - `[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 |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if api/index.rst was deleted or modified
git log --all --full-history --oneline -- '**/api/index.rst' | head -5
# Check for references to api/index in recent commits
git log --all -p --grep='api/index' | head -50Repository: datafolklabs/cement
Length of output: 232
🏁 Script executed:
# Check if api/index.rst currently exists
find . -name "api" -type d -o -name "index.rst" -type f | grep -E "(api|index)" | head -20Repository: datafolklabs/cement
Length of output: 204
🏁 Script executed:
# Check for toctree files and their contents
find docs -name "*.rst" -type f | xargs grep -l "toctree" 2>/dev/null | head -5Repository: datafolklabs/cement
Length of output: 178
🏁 Script executed:
# Look for recent changes involving api/index
git log --all -p --follow -- "docs/api/index.rst" 2>/dev/null | head -100Repository: datafolklabs/cement
Length of output: 45
🏁 Script executed:
# Check the structure of docs directory
ls -la docs/ 2>/dev/null | grep -E "^d|^-" | head -20Repository: datafolklabs/cement
Length of output: 222
🏁 Script executed:
# Examine the main index.rst file to see toctree structure
cat docs/source/index.rst | head -80Repository: datafolklabs/cement
Length of output: 409
🏁 Script executed:
# Look for any toctree directives mentioning api
grep -r "toctree" docs/source/index.rst -A 20 | head -40Repository: datafolklabs/cement
Length of output: 147
Correct changelog entry to accurately describe the actual change.
The changelog entry "Wire api/index into top-level toctree" is inaccurate. The api/index.rst file does not exist in the repository and was deleted. The toctree in docs/source/index.rst now directly references the api subdirectories (api/core/index, api/utils/index, api/ext/index) rather than routing through a parent api/index.rst file.
Update line 335 to reflect the actual change, such as "[docs] Delete orphan api/index.rst" or similar wording that describes removal rather than wiring.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CHANGELOG.md` at line 335, Update the changelog entry on line 335 to
accurately describe the change: replace the incorrect "[docs] Wire api/index
into top-level toctree" with a message reflecting removal of the orphan file
(for example "[docs] Remove orphan api/index.rst; reference api/core/index,
api/utils/index, api/ext/index directly in docs/source/index.rst"). Ensure the
new entry mentions deletion of api/index.rst and that docs/source/index.rst now
references the api subdirectories directly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 5 of the Cement 3 modernization milestone: deprecations cleanup,
docs build hygiene, and planning-side security-tooling stubs. Six
plans executed across six waves; verification passed 12/12 must-haves;
post-verification code review surfaced two real regressions and four
sister findings, all fixed before this PR. All project gates (ruff,
mypy, audit-public-api, 100% test coverage, zero-warnings docs build)
green.
Changes
Deprecations (Plan 05-01, 05-03)
[core.deprecations]Pin every entry inDEPRECATIONSto a concreteremoval version (
Cement v3.2.0). Drop the trailing period from the3.0.10-1value so the runtime warning no longer renders as..before the GitBook URL (CR-02 from review).
[ext.logging]Tighten removal-version language in theset_leveland
fataldeprecation docstrings —Cement v3.2.0named explicitly,with double-backtick RST for inline code.
[ext.smtp]Document thesend()bool-return → senderrs-dictcontract change as a
.. deprecated:: 3.0.16admonition so autodocrenders the deprecation in HTML.
DEPRECATIONS.md(new, repo root): in-repo touchpoint with a 5-elementblock per ID (Surface / Since / Removal / migration prose / GitBook
back-link). Anchors use the dotted form (
#3.0.8-1) so the linkemitted by
cement.core.deprecations.deprecate()lands on the sameGitBook fragment.
Docs build hygiene (Plan 05-02, 05-04, +follow-ups)
[sphinx]Resolve all five Sphinx warnings underpdm run sphinx-build: drop unsupportedlogotheme option, renamedisplay_version→version_selector(sphinx_rtd_theme 3.0+),string-quote a
list[str]autodoc return annotation incore.interface, reflow thecmd()Returns docstring so theinline-literal stays single-line, delete the unused
docs/source/api/index.rstorphan.[make]Wire-W(warnings-as-errors) intomake docsand switchthe recipe from
;to&&chaining (CR-01 from review). Without&&, the recipe's exit code came from the trailingcd ..(always0), so the zero-warnings gate this phase was meant to install was
non-functional — it now genuinely fails the build on any new warning.
[docs]Exposecement.core.deprecationsin the Sphinx APIreference (was missing entirely). Adds
docs/source/api/core/deprecations.rst+ toctree entry, plusminimal docstrings on the module,
DEPRECATIONSdict, anddeprecate()so the autodoc page renders meaningful content ratherthan an empty stub. Closes a real DEPREC-02 gap surfaced during
review: the module that emits every runtime DeprecationWarning was
internally imported by four sites but never had a
:mod:page.[docs]Fixstderror→stderrtypo incement.utils.shell:cmd()andexec_cmd()Returns docstrings (4occurrences). Example variables and runtime code already used the
correct name; only the prose mismatched. Sister fix to Plan 05-02's
inline-literal RST work, which reflowed the same prose without
catching the typo.
Public-facing docs (Plan 05-05, +follow-up)
README.md— drop both Travis-CI surfaces (badge + More Informationlink); CI moved to GitHub Actions long ago.
.github/CONTRIBUTING.md— align with Conventional Commits +atomic-per-concern discipline; reference
make commit; back-link to../CLAUDE.md. Remove the orphaned[Commit Guidelines]:reference-link definition that lost its body callsites in the Plan
05-05 rewrite (WR-01 follow-up).
Planning-side security stubs (Plan 05-06)
.planning/REQUIREMENTS.md— expandSECv2-01..03(pip-audit,bandit, SAST/CodeQL) with phase-shaped scope blocks (Tool, Make
target, CI placement, Config, New dev-dep, Exit behavior) so the
future security-tooling milestone has hand-off-ready starting points.
.planning/codebase/CONVENTIONS.mdPEP 604/585 refresh isintentionally not part of this PR — it's a transient planning
artifact and lands via the post-merge archive commit.)
CHANGELOG hygiene
[docs] Wire api/index into top-level toctreeentry wasfactually wrong — Plan 05-02 actually deleted the orphan. Replaced
with text matching the actual repo state (
docs/source/index.rstreferences
api/core/index,api/utils/index,api/ext/indexdirectly).
Acceptance status
cement.core.deprecations, with documented Sphinx-vs-GitBook split)make docsis zero-warnings (genuinely enforced via-W+&&)cement/VERIFICATION.md status:
passed. 12/12 must-haves verified (1 via thedocumented CONTEXT.md D-05/D-06 override that reinterprets DEPREC-02's
medium from
docs/source/deprecations.rstto repo-rootDEPRECATIONS.md— Sphinx is strictly API reference perdocs/source/index.rst; developer narrative lives at builtoncement.com).Files touched
Code:
cement/core/deprecations.pycement/core/interface.pycement/ext/ext_logging.pycement/ext/ext_smtp.pycement/utils/shell.pydocs/source/conf.pydocs/source/api/core/deprecations.rst(new)docs/source/api/core/index.rst(toctree entry)docs/source/api/index.rst(deleted — orphan)Build / docs / contributor surfaces:
MakefileREADME.md.github/CONTRIBUTING.mdDEPRECATIONS.md(new)CHANGELOG.mdStructural planning state:
.planning/PROJECT.md.planning/REQUIREMENTS.md.planning/ROADMAP.md.planning/STATE.mdTest plan
make comply— ruff + mypy cleanmake audit-public-api— public surface byte-identicalmake test— 320 passing, 100% coverage heldmake docs— zero-warnings build under-W(clean baseline)make docsnow exitsnon-zero (verifies the
&&fix bites where the prior;formsilently passed)
cement.core.deprecations.deprecate('3.0.10-1'), confirmthe runtime warning has a single period before
See: ...(no..)SMTPMailHandler.send()shows the.. deprecated:: 3.0.16admonition correctlydocs/build/api/core/deprecations.htmlrenders with bothDEPRECATIONSanddeprecatedocumented (not an empty stub)docs/build/api/utils/shell.htmlrenderscmd()andexec_cmd()withstderr(nostderror) in the Returns prose🤖 Generated with Claude Code