Skip to content

Describe the web interface in the user guide - #73

Merged
dmccoystephenson merged 1 commit into
mainfrom
feature/document-web-interface
Nov 14, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
feature/document-web-interface

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

  • USER_GUIDE.md gains a Using the web interface section describing the page served in web mode, verified against src/main/resources/static/app.js and index.html:
    • the Create New Backup form: one user or organization per submission, button disabled with a spinner until the backup finishes (including a possible rate-limit wait), the server's success or error message shown below the form, field cleared and status reloaded on success;
    • the Backup Status section: loaded on page open and by Refresh, totals plus every repository with its last-updated time, list/card/gallery views (gallery colored per user/org with a color key), view choice remembered by the browser, and the empty and failed-to-load states.
  • The web-mode quick start now links to that section; previously it only said to open http://localhost:8080.
  • CHANGELOG.md records the change under [Unreleased] → Fixed, following the existing "Documentation accuracy:" entries.

This is a Stage A documentation accuracy cycle. No tracking issue — the gap was found during the documentation sweep. COMMANDS.md, CONFIG.md and README.md were swept against BackupCommandLineRunner, BackupController, BackupService, ScheduledBackupService, GitHubService, RateLimitNoticeHandler and the application*.properties files, and no drift was found there.

Deferred: #8 (missing LICENSE) remains open because choosing the license text, copyright holder and year is a maintainer decision.

Test plan

  • mvn test — 228 tests run, 0 failures, 0 errors, 1 skipped (DocumentationVersionTest reads USER_GUIDE.md and still passes)
  • Each claim in the new section traced to app.js / index.html / BackupController
  • CI Build green on the PR head

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

The guide only said to open http://localhost:8080. It now describes the
backup form (one name per submission, server message shown on success or
failure) and the status section (totals, refresh, remembered list, card
and gallery views), as implemented in static/app.js and index.html.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric (anchored on CI run 43556750039: build and docker-build both pass on the PR head; local mvn test ran 228 tests, 0 failures, 1 skipped):

  • Scope: PASS — only USER_GUIDE.md (new section plus one quick-start link) and CHANGELOG.md (one Fixed entry) are modified; both are needed for the documented gap.
  • Tests-new: PASS (not applicable) — no code was added.
  • Tests-fix: PASS (not applicable) — no bug fix; documentation only.
  • Sibling structure: PASS — the new ### Using the web interface heading sits under ## Common Scenarios alongside the other ### scenarios; the CHANGELOG entry follows the existing "Documentation accuracy:" form under [Unreleased] → Fixed.
  • Sibling renames: PASS (not applicable) — no renames.
  • Docs: PASS — COMMANDS.md already documents both endpoints the page calls and is linked from the new section; CONFIG.md's server.port is referenced; README.md needs no change.
  • Issue resolution: PASS (not applicable) — no Closes #N; the gap was found during the documentation sweep.
  • CI: PASS — see the run above.
  • Config-doc / command-doc parity: PASS (not applicable) — no new properties, flags or endpoints.
  • Package placement: PASS (not applicable).
  • No credential leakage: PASS — no token handling touched.

Findings:

  • USER_GUIDE.md (Using the web interface, Create New Backup bullet) — verified against app.js: the field is cleared and loadStatus() runs (after a 1 s delay) only when data.success is true; an HTTP error shows errorData.message, which is what BackupController returns for 400 and 500. Accurate.
  • USER_GUIDE.md (Backup Status bullet) — minor inconsistency: the failed-to-load text is quoted verbatim, but the empty state ("No backups found yet. Create your first backup above!") is only paraphrased. Left as-is; paraphrasing it keeps the guide from going stale if the UI wording changes, and the failure text is quoted because it is what a troubleshooting reader searches for.

Ready to merge: docs-only, no do-not-auto-merge paths touched.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 52ef07a into main Nov 14, 2026
2 checks passed
@dmccoystephenson
dmccoystephenson deleted the feature/document-web-interface branch November 14, 2026 04:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant