domverse/photoanalyzer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

US09-05 — Automate Documentation Acceptance #106

New Issue
Closed
opened 2026-08-23 15:06:17 +02:00 by domverse · 3 comments
domverse commented 2026-08-23 15:06:17 +02:00
Owner
Copy Link

Source specification: delivery_backlog/stories/US09-05-docs-gate.md

US09-05 — Automate Documentation Acceptance

Epic: E09

As a release owner, I want one gate that proves the documentation still describes the
application, so that a change to the code cannot quietly make the manuals wrong.

Acceptance criteria

  • One documented command runs every documentation check and retains its evidence, in the
    shape the release and container gates already use.
  • The gate fails when: an internal link or anchor is dead; a page is unreachable from the
    index; an image is referenced but missing or present but unreferenced; a documented
    setting, command, exit code, error code, or state does not exist in the code; a code
    path exists that the documentation is required to cover and does not.
  • The gate regenerates the screenshots and fails when a regenerated image no longer
    matches the committed one beyond a stated tolerance, so a UI change that invalidates the
    manual is a red build rather than a discovery months later.
  • The gate renders every documentation page in a real browser and fails on any console
    error or CSP violation, and asserts that script-src contains neither 'unsafe-eval'
    nor 'unsafe-inline'.
  • The checks run on a phase_i marker; CI runs the gate, and the earlier epic suites keep
    running unchanged.
  • The README and the application's documentation index point at each other, so neither is
    the forgotten copy.
  • Documentation stories are mapped in the story traceability matrix like every other
    story.

Automated tests

  • The gate's own contract is testable without a browser: a seeded broken link, a missing
    image, an undocumented error code, and a stale screenshot each fail it, and a clean tree
    passes.
  • The full documentation suite runs on phase_i in CI.

Dependencies

  • US09-01 through US09-04
Source specification: [delivery_backlog/stories/US09-05-docs-gate.md](https://git.domverse-berlin.eu/domverse/photoanalyzer/src/branch/main/delivery_backlog/stories/US09-05-docs-gate.md) # US09-05 — Automate Documentation Acceptance Epic: [E09](../E09-documentation.md) As a release owner, I want one gate that proves the documentation still describes the application, so that a change to the code cannot quietly make the manuals wrong. ## Acceptance criteria - One documented command runs every documentation check and retains its evidence, in the shape the release and container gates already use. - The gate fails when: an internal link or anchor is dead; a page is unreachable from the index; an image is referenced but missing or present but unreferenced; a documented setting, command, exit code, error code, or state does not exist in the code; a code path exists that the documentation is required to cover and does not. - The gate regenerates the screenshots and fails when a regenerated image no longer matches the committed one beyond a stated tolerance, so a UI change that invalidates the manual is a red build rather than a discovery months later. - The gate renders every documentation page in a real browser and fails on any console error or CSP violation, and asserts that `script-src` contains neither `'unsafe-eval'` nor `'unsafe-inline'`. - The checks run on a `phase_i` marker; CI runs the gate, and the earlier epic suites keep running unchanged. - The README and the application's documentation index point at each other, so neither is the forgotten copy. - Documentation stories are mapped in the story traceability matrix like every other story. ## Automated tests - The gate's own contract is testable without a browser: a seeded broken link, a missing image, an undocumented error code, and a stale screenshot each fail it, and a clean tree passes. - The full documentation suite runs on `phase_i` in CI. ## Dependencies - US09-01 through US09-04
domverse self-assigned this 2026-08-23 15:06:17 +02:00
domverse added this to the E09 — Product Documentation milestone 2026-08-23 15:07:42 +02:00
domverse added this to the Photo Analyzer Delivery project 2026-08-23 15:09:36 +02:00
domverse added a new dependency 2026-08-23 15:10:18 +02:00
#102 US09-01 — Serve the Documentation Inside the Application
domverse added a new dependency 2026-08-23 15:10:18 +02:00
#103 US09-02 — Write the Installation and Operations Manual
domverse added a new dependency 2026-08-23 15:10:19 +02:00
#104 US09-03 — Write the Architecture Overview
domverse added a new dependency 2026-08-23 15:10:19 +02:00
#105 US09-04 — Write the User Manual with Generated Screenshots
domverse removed their assignment 2026-08-23 15:15:09 +02:00
domverse added status/in-progress and removed status/backlog labels 2026-08-23 23:43:55 +02:00
domverse self-assigned this 2026-08-23 23:43:56 +02:00
domverse commented 2026-08-23 23:43:56 +02:00
Author
Owner
Copy Link

Claimed for implementation on branch us/US09-05-automate-documentation-acceptance.

Claimed for implementation on branch `us/US09-05-automate-documentation-acceptance`.
domverse added status/review and removed status/in-progress labels 2026-08-24 00:22:39 +02:00
domverse commented 2026-08-24 00:22:40 +02:00
Author
Owner
Copy Link

Submitted for review: #111

Tests passed:

  • work_item/scripts/python -m unittest discover -s work_item/tests -v
  • work_item/scripts/python -m pytest tests -q
  • work_item/scripts/python -m pytest tests -m phase_i -q
Submitted for review: https://git.domverse-berlin.eu/domverse/photoanalyzer/pulls/111 Tests passed: - `work_item/scripts/python -m unittest discover -s work_item/tests -v` - `work_item/scripts/python -m pytest tests -q` - `work_item/scripts/python -m pytest tests -m phase_i -q`
domverse added status/done and removed status/review labels 2026-08-24 00:23:04 +02:00
domverse commented 2026-08-24 00:23:05 +02:00
Author
Owner
Copy Link

Completed and merged via PR #111.

Completed and merged via PR #111.
domverse moved this to Done in Photo Analyzer Delivery on 2026-08-24 16:51:08 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/backend
Backend services, jobs, or API
 area/database
Schema, persistence, migration, or queries
 area/documentation
Manuals, architecture notes, and in-app documentation
 area/filesystem
Filesystem identity, mutation, or storage
 area/frontend
Browser UI and client-side application
 area/integration
External tools or provider integrations
 area/testing
Automated test suites, fixtures, and tooling
 priority/critical
Release-blocking safety or correctness
 priority/high
Important phase outcome
 priority/normal
Normal planned work
 status/backlog
Awaiting dependency eligibility or prioritization
 status/blocked
Cannot proceed without an explicit resolution
 status/done
Merged, tested, and completed
 status/in-progress
Currently being implemented
 status/ready
Eligible to be claimed
 status/review
Submitted in a pull request for review
 type/documentation
Written documentation delivered as a product artefact
 type/feature
User-facing or domain capability
 type/hardening
Security, resilience, operations, or release hardening
 type/migration
Donor extraction, migration, or legacy consolidation
 type/test
Automated test infrastructure or acceptance coverage
No Label area/documentation area/testing priority/normal status/done type/test
Milestone
No items
No Milestone E09 — Product Documentation
Projects
Clear projects
No project Photo Analyzer Delivery
Assignees
Clear assignees
domverse
No Assignees domverse
1 Participants
Notifications
Due Date
No due date set.
Depends on
#102 US09-01 — Serve the Documentation Inside the Application
domverse/photoanalyzer
#103 US09-02 — Write the Installation and Operations Manual
domverse/photoanalyzer
#104 US09-03 — Write the Architecture Overview
domverse/photoanalyzer
#105 US09-04 — Write the User Manual with Generated Screenshots
domverse/photoanalyzer
Reference: domverse/photoanalyzer#106
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?