Skip to content

docs: carry the technical-voice pass into the surfaces #88 did not touch - #89

Merged
kmadan merged 1 commit into
mainfrom
docs/technical-voice-additive
Aug 30, 2026
Merged

docs: carry the technical-voice pass into the surfaces #88 did not touch#89
kmadan merged 1 commit into
mainfrom
docs/technical-voice-additive

Conversation

@kmadan

@kmadan kmadan commented Aug 30, 2026

Copy link
Copy Markdown
Contributor

🚀 Overview

Carries the technical-voice documentation pass into the 19 surfaces #88 did not
touch. README.md, README-pypi.md and aicertify/cli.py are deliberately
excluded, so nothing merged in #88 is reverted.

This work existed on docs/technical-voice (5ab4d11), which branched from the
same base as #88 and was never opened as a PR. That branch can be deleted once
this and its companion corrections PR are merged.

📜 Changes Made

The diagram mismatch

#88 updated the policy count to 92 in the README alt text. The count a
reader actually sees is rendered inside the SVG, which still read 91.
main currently says 92 in four places of prose and 91 in four rendered images.

diagram2 and diagram3 now read 92 in both themes. diagram1 and diagram5
relabel "audit-ready report" as "evidence report", matching the README's
language.

Translated READMEs

pyproject.toml declares requires-python = ">=3.12,<3.13" — 3.12 only. The
"Python 3.12+" badge overstated the supported range. Corrected to 3.12 in all
four translations. The English README and PyPI page still carry the same
overstatement and are fixed in the companion PR
, together with four other
defects.

Prose-only files

docs/INDEX.md, docs/adapters.md, docs/integrations/github-actions.md,
docs/why-aicertify.md, docs/writing-an-evaluator.md, examples/README.md.
No figure, threshold, command or link target changes in these six.

Submodule

0482ec94321e7a, which is the v2.0.0 tag. The branch that set the
previous pin was named for 2.0.0 but pinned the commit before the tag.

The two trees differ by one comment line in
helper_functions/declarations.rego (171 → 170 fields). No policy behaviour
changes. Coverage totals are unchanged at policies: 92, policies_with_tests: 92, policies_with_empty_input_test: 92.

🎯 How to Test

git submodule update --init --recursive aicertify/opa_policies
cd aicertify/opa_policies && git describe --tags     # -> v2.0.0
jq -c .totals docs/coverage/coverage.json            # -> policies: 92

Verified locally: no 91 ... policies string remains in any tracked file, every
relative link in the six carried docs resolves, and the submodule checks out at
v2.0.0.

📚 Documentation

  • ✅ Diagrams, translations, explanatory docs, examples index
  • ✅ No API, CLI or policy behaviour changes

#88 rewrote README.md, README-pypi.md and the CLI help. The same pass had been
prepared for the explanatory docs, the examples index, the translated READMEs
and the diagrams, on a branch that was never opened as a pull request. Those
nineteen files are carried across here. The three files #88 already rewrote are
deliberately excluded, so nothing merged in #88 is reverted.

The diagrams correct a mismatch #88 introduced. #88 updated the policy count in
the README alt text to 92, but the count a reader sees is rendered inside the
SVG, which still read 91. diagram2 and diagram3 now read 92 in both themes, so
the images agree with the prose. diagram1 and diagram5 relabel "audit-ready
report" as "evidence report", matching the language the README now uses.

The four translated READMEs carry one correction each: pyproject declares
requires-python = ">=3.12,<3.13", so the "Python 3.12+" badge overstated the
supported range. It now reads 3.12. The English surfaces still carry the same
overstatement and are corrected separately.

docs/INDEX.md, docs/adapters.md, docs/integrations/github-actions.md,
docs/why-aicertify.md, docs/writing-an-evaluator.md and examples/README.md
receive the register pass only. No figure, threshold, command or link target
changes in those six files.

The submodule moves from 0482ec9 to 4321e7a, which is the v2.0.0 tag. The
branch that set the previous pin was named for 2.0.0 but pinned the commit
before the tag. The two trees differ by one comment line in
helper_functions/declarations.rego, correcting 171 to 170 fields; no policy
behaviour changes, and coverage totals stay at 92 policies, 92 with tests and
92 with empty-input tests.

Verified: no "91 policies" string remains in any tracked file, every relative
link in the six carried docs resolves, and the submodule checks out at v2.0.0.
@github-actions github-actions Bot added 📝 documentation Improvements or additions to documentation 🚀 enhancement New feature or request 🤝 good first issue Good for newcomers labels Aug 30, 2026
@kmadan
kmadan merged commit c929126 into main Aug 30, 2026
7 checks passed
@kmadan
kmadan deleted the docs/technical-voice-additive branch August 30, 2026 05:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

📝 documentation Improvements or additions to documentation 🚀 enhancement New feature or request 🤝 good first issue Good for newcomers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant