DESIGN.md — tool matrix, API table, version requirements #120

New issue

Closed

opened 2026-08-29 03:29:23 +00:00 by david · 1 comment

david commented

2026-08-29 03:29:23 +00:00

Owner

Summary

Update extensions/forgejo/docs/DESIGN.md for the Actions tooling: add the 5 tools to the tool matrix, add the Actions endpoints to the API table, move Actions out of Non-Goals, add the v16+ version requirement, and move v17+ features to Future Enhancements.

Background

Part of the Forgejo Actions tooling feature (tracking issue #111). Docs land after code + tests are green (#118), in the same pass as the README (#119). DESIGN.md currently documents the ~31-tool matrix and API mapping with a Non-Goals section; it must be brought in line with the shipped Actions tools.

Implementation Details

Tool matrix: add forgejo_action_runs, forgejo_action_run_view, forgejo_action_jobs, forgejo_action_job_log, forgejo_action_run_logs (5 tools → ~36 total).
API table: add the Actions endpoints (GET /repos/{owner}/{repo}/actions/runs, .../runs/{run_id}, .../runs/{run_id}/jobs, .../jobs/{job_id}/logs?attempt=, .../runs/{run_id}/logs (ZIP)) with notes on caching behavior (metadata live, logs cache-first).
Non-Goals: remove Actions-related non-goals; keep the rest.
Add version requirements note: v16+ for the actions endpoints.
Future Enhancements (v17+): job details endpoint, ?step= / ?q= / ?format=ndjson, artifacts — move from wherever they currently live into this section.
Update architecture diagram / tool-count boxes if the doc has them (a previous phase updated them to ~31 tools).

Acceptance Criteria

DESIGN.md tool matrix lists all 5 new tools (count updated).
API table includes the 5 Actions endpoints with cache semantics noted.
Non-Goals no longer contradict Actions tooling; v17+ items are under Future Enhancements.
v16+ version requirement is stated.
Consistent with README (#119) and the shipped implementation.

Test Plan

Read DESIGN.md top to bottom; grep -n -i action to confirm no stale Non-Goal references remain.
Cross-check the endpoint table against src/actions.ts.

### Summary Update `extensions/forgejo/docs/DESIGN.md` for the Actions tooling: add the 5 tools to the tool matrix, add the Actions endpoints to the API table, move Actions out of Non-Goals, add the v16+ version requirement, and move v17+ features to Future Enhancements. ### Background Part of the Forgejo Actions tooling feature (tracking issue **#111**). Docs land after code + tests are green (**#118**), in the same pass as the README (**#119**). DESIGN.md currently documents the ~31-tool matrix and API mapping with a Non-Goals section; it must be brought in line with the shipped Actions tools. ### Implementation Details - Tool matrix: add `forgejo_action_runs`, `forgejo_action_run_view`, `forgejo_action_jobs`, `forgejo_action_job_log`, `forgejo_action_run_logs` (5 tools → ~36 total). - API table: add the Actions endpoints (`GET /repos/{owner}/{repo}/actions/runs`, `.../runs/{run_id}`, `.../runs/{run_id}/jobs`, `.../jobs/{job_id}/logs?attempt=`, `.../runs/{run_id}/logs` (ZIP)) with notes on caching behavior (metadata live, logs cache-first). - Non-Goals: remove Actions-related non-goals; keep the rest. - Add version requirements note: **v16+** for the actions endpoints. - Future Enhancements (v17+): job details endpoint, `?step=` / `?q=` / `?format=ndjson`, artifacts — move from wherever they currently live into this section. - Update architecture diagram / tool-count boxes if the doc has them (a previous phase updated them to ~31 tools). ### Acceptance Criteria - [ ] DESIGN.md tool matrix lists all 5 new tools (count updated). - [ ] API table includes the 5 Actions endpoints with cache semantics noted. - [ ] Non-Goals no longer contradict Actions tooling; v17+ items are under Future Enhancements. - [ ] v16+ version requirement is stated. - [ ] Consistent with README (#119) and the shipped implementation. ### Test Plan - Read DESIGN.md top to bottom; `grep -n -i action` to confirm no stale Non-Goal references remain. - Cross-check the endpoint table against `src/actions.ts`.

david added this to the M7 - Actions documentation (last step) milestone

2026-08-29 03:29:23 +00:00

david added the

documentation

label

2026-08-29 03:29:23 +00:00

david referenced this issue

2026-08-29 03:29:32 +00:00

Final review — docs consistency + npm run check/test green #121

david referenced this issue

2026-09-18 06:09:15 +00:00

README.md — Actions tools table, examples, caveats #119

david commented

2026-09-18 06:14:27 +00:00

Author

Owner

All acceptance criteria verified against the file, README (#119), and src/actions.ts:

✅ Tool matrix lists all 5 Actions tools; Goals count updated to ~37 (20 issues + 11 PRs + 1 support + 5 actions)
✅ API table includes all 5 Actions endpoints with cache semantics noted (logs cache-first, metadata live)
✅ Non-Goals contain no stale Actions references; v17+ items under Future Enhancements
✅ v16+ version requirement stated in Version Requirements
✅ Consistent with README and shipped implementation

Remaining stale tool-count boxes fixed in e968334 (diagram 16→20, risks table ~23→~37, artifacts added to the v17+ Future Enhancements item). Closing.

All acceptance criteria verified against the file, README (#119), and `src/actions.ts`: - ✅ Tool matrix lists all 5 Actions tools; Goals count updated to ~37 (20 issues + 11 PRs + 1 support + 5 actions) - ✅ API table includes all 5 Actions endpoints with cache semantics noted (logs cache-first, metadata live) - ✅ Non-Goals contain no stale Actions references; v17+ items under Future Enhancements - ✅ v16+ version requirement stated in Version Requirements - ✅ Consistent with README and shipped implementation Remaining stale tool-count boxes fixed in `e968334` (diagram 16→20, risks table ~23→~37, artifacts added to the v17+ Future Enhancements item). Closing.

david closed this issue

2026-09-18 06:14:29 +00:00

david referenced this issue

2026-09-18 06:44:46 +00:00

Open PR — issue-111: add forgejo actions tools #122