Deliver TechDocs for one real Forgejo repository #25

Closed
opened 2026-11-07 21:51:25 +00:00 by martin · 2 comments
Owner

Goal

Prove the complete documentation workflow in one real repository before broad rollout.

Acceptance criteria

  • Select one pilot repository and add a working documentation build and catalog annotation.
  • Documentation renders in Backstage and appears in search.
  • Document authoring, preview, and troubleshooting.
  • Record the CI publishing/storage approach needed for a hosted portal, including access controls for private docs.
  • Keep documentation build credentials backend-side or in CI.

Depends on

Phase

2 — Useful developer workflows

Completion evidence

  • Pilot source/build and corrected Gitea branch reference: Personal/recurring-events#66 and #67 (merged).
  • Backstage TechDocs runbook and controlled browser coverage: #61 (merged).
  • Local render/search verification and automated checks are recorded in the progress comment below.
## Goal Prove the complete documentation workflow in one real repository before broad rollout. ## Acceptance criteria - [x] Select one pilot repository and add a working documentation build and catalog annotation. - [x] Documentation renders in Backstage and appears in search. - [x] Document authoring, preview, and troubleshooting. - [x] Record the CI publishing/storage approach needed for a hosted portal, including access controls for private docs. - [x] Keep documentation build credentials backend-side or in CI. ## Depends on - #28 — Support repository-owned catalog metadata (complete). - Personal/recurring-events#65 — Add the TechDocs source, build, and authoring guidance. ## Phase 2 — Useful developer workflows ## Completion evidence - Pilot source/build and corrected Gitea branch reference: Personal/recurring-events#66 and #67 (merged). - Backstage TechDocs runbook and controlled browser coverage: #61 (merged). - Local render/search verification and automated checks are recorded in the progress comment below.
Author
Owner

Progress

  • Selected Personal/recurring-events as the pilot. The docs source/build and catalog annotation are merged in recurring-events#66, with the Gitea branch-ref correction in #67; the repository-local issue #65 is closed. nix develop --command just docs and nix fmt passed.
  • Verified the merged pilot through Backstage using a local MkDocs generator override: the TechDocs home/API/development pages and metadata returned HTTP 200, and a TechDocs search query for recurring events returned 12 results.
  • Backstage runbook and controlled E2E fixture coverage are in PR #61. Local checks: bun run tsc, bun run prettier:check, and bun run test:e2e (7/7 passed). PR review CI passed; application-checks CI was still pending when this update was written.

Decisions

  • For a Forgejo/Gitea repository source, TechDocs needs a branch-tree URL such as .../src/branch/main/; a root source-location plus dir:. fails because the Gitea reader cannot infer the branch. The E2E fixture uses local dir:. and mocks generated TechDocs responses, keeping it independent of Forgejo and Docker.
  • Keep the local Docker generator/local publisher for now. For hosted publishing, build in CI and publish to private object storage with separate CI write-only and backend read-only credentials. Do not enable private repository docs until the authorization policy in #30 is in place.

Remaining

  • Review and merge Backstage PR #61, then update the acceptance criteria and close #25 if no review changes are requested.
## Progress - Selected `Personal/recurring-events` as the pilot. The docs source/build and catalog annotation are merged in [recurring-events#66](https://code.martials.no/Personal/recurring-events/pulls/66), with the Gitea branch-ref correction in [#67](https://code.martials.no/Personal/recurring-events/pulls/67); the repository-local issue #65 is closed. `nix develop --command just docs` and `nix fmt` passed. - Verified the merged pilot through Backstage using a local MkDocs generator override: the TechDocs home/API/development pages and metadata returned HTTP 200, and a TechDocs search query for `recurring events` returned 12 results. - Backstage runbook and controlled E2E fixture coverage are in [PR #61](https://code.martials.no/Personal/backstage/pulls/61). Local checks: `bun run tsc`, `bun run prettier:check`, and `bun run test:e2e` (7/7 passed). PR review CI passed; application-checks CI was still pending when this update was written. ## Decisions - For a Forgejo/Gitea repository source, TechDocs needs a branch-tree URL such as `.../src/branch/main/`; a root `source-location` plus `dir:.` fails because the Gitea reader cannot infer the branch. The E2E fixture uses local `dir:.` and mocks generated TechDocs responses, keeping it independent of Forgejo and Docker. - Keep the local Docker generator/local publisher for now. For hosted publishing, build in CI and publish to private object storage with separate CI write-only and backend read-only credentials. Do not enable private repository docs until the authorization policy in #30 is in place. ## Remaining - Review and merge Backstage PR #61, then update the acceptance criteria and close #25 if no review changes are requested.
Author
Owner

Result

  • The recurring-events MkDocs site builds successfully with nix develop --command just docs; the pilot's TechDocs pages and metadata rendered through Backstage, and search returned 12 TechDocs results for recurring events.
  • Backstage automated checks passed: bun run tsc, bun run prettier:check, and controlled E2E tests (7/7). Woodpecker application checks and PR review both succeeded for #61.
  • Hosted publishing is documented as CI build to private object storage, with CI write-only and backend read-only credentials. Private repository docs remain disabled until the authorization policy in #30 is implemented; the issue required recording the approach, not enabling private docs.

All acceptance criteria are satisfied. Closing #25.

## Result - The recurring-events MkDocs site builds successfully with `nix develop --command just docs`; the pilot's TechDocs pages and metadata rendered through Backstage, and search returned 12 TechDocs results for `recurring events`. - Backstage automated checks passed: `bun run tsc`, `bun run prettier:check`, and controlled E2E tests (7/7). Woodpecker application checks and PR review both succeeded for #61. - Hosted publishing is documented as CI build to private object storage, with CI write-only and backend read-only credentials. Private repository docs remain disabled until the authorization policy in #30 is implemented; the issue required recording the approach, not enabling private docs. All acceptance criteria are satisfied. Closing #25.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/backstage#25
No description provided.