镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

docs: add troubleshooting, getting started, a changelog, its CI check, and a PR template - #29

Merged
thebrandonlucas merged 1 commit into
docs/cli-referencefrom
docs/cli-troubleshooting
Oct 20, 2026
Merged

thebrandonlucas merged 1 commit into
docs/cli-referencefrom
docs/cli-troubleshooting

Conversation

@thebrandonlucas

@thebrandonlucas thebrandonlucas commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Stack: master ← #26 ← #27 ← #28 ← #29 ← #30 ← #55 ← #60. #20, #22, #57, #24 and #19 are merged.

  • Troubleshooting (docs/guides/troubleshooting.md): an entry per exit code and per credential_problem (no_credential, multiple_credentials, unknown_credential, empty_api_key, bound_elsewhere, auth_url_mismatch), plus expired logins, API-key discovery, HTTP 401/403 (account and checkout credentials), a locked OS credential store, feature_flag_disabled, and quote_required. Each heading is the literal code or message, so search finds it.
  • Getting started (docs/getting-started.md): one path from install through login, a saved profile, a mutinynet wallet, a received 1,000 sats, and the same receive scripted with --json and jq.
  • Changelog: CHANGELOG.md (Keep a Changelog style, hand-written) seeded with the changes since 0.1.0, including this stack.
  • Keeping it current: a Changelog workflow fails a PR that changes src/cli.rs or api/commands.json without CHANGELOG.md, unless it has the no-changelog label. It reruns on label changes, so it is a separate workflow from CI. AGENTS.md states the rule and that the check is a heuristic: it fires on test-only src/cli.rs changes and misses user-visible changes in other files.
  • PR template: asks for the changelog entry, the verification gate, the voltage-pr-review pass with tests for new error paths, the CRAP result (highest score and each function at or above 20), and each check not run with its reason, as AGENTS.md "Before you request review" requires.

Tests: troubleshooting must have an entry for every exit code and every CredentialProblem. The exit codes come from #28's error_kinds() and the problems from an exhaustive match, so a new kind or problem fails to compile until it has an entry. The docs example checks also read CHANGELOG.md and the tutorial, so the tutorial's commands parse and its changes pass as offline dry runs.

Changes after review

Not done here

  • The tutorial is unverified against a live account. The plan's acceptance check is a new teammate following it on a test network.
  • A staging guide waits for deployment URLs in profiles (plan 05).

Checks

On 574e085:

  • cargo fmt --check, cargo clippy --locked --all-targets -- -D warnings, cargo machete --with-metadata: pass.
  • cargo test --locked: 103 unit and 86 integration tests pass. VOLTAGE_BLESS=1 cargo test --locked leaves the tree clean.
  • python3 scripts/check-coverage.py: pass.
  • CRAP (scripts/crap-report.sh): no function at or above 20. Highest is api::wait_for_payment at 19.24, unchanged from or lower than master (19.66).
  • Skill review: voltage-pr-review and the voltage-backend-engineering Rust checklist, against the stack base. Findings are fixed in this commit.

Not run: the staging and live tutorials, which need credentials.

@thebrandonlucas
thebrandonlucas added this pull request to stack #25 October 13, 2026 19:09
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch 2 times, most recently from 2d19d0b to 61af70c Compare October 19, 2026 13:14
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch 4 times, most recently from a0df0b3 to d6b3fc3 Compare October 19, 2026 18:39
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch 2 times, most recently from b4ca251 to 39b720c Compare October 19, 2026 19:11
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch from 39b720c to ba7701d Compare October 19, 2026 19:19
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch from ba7701d to 01df020 Compare October 20, 2026 00:20
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch from 01df020 to ad2267b Compare October 20, 2026 11:59
@thebrandonlucas
thebrandonlucas removed this pull request from stack #25 October 20, 2026 11:59
@thebrandonlucas
thebrandonlucas added this pull request to stack #58 October 20, 2026 11:59
@thebrandonlucas thebrandonlucas changed the title docs: add troubleshooting, getting started, and a changelog docs: add troubleshooting, getting started, a changelog, its CI check, and a PR template Oct 20, 2026
@thebrandonlucas thebrandonlucas added the human review wanted CI passes; ready for a human reviewer label Oct 20, 2026
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch from ad2267b to 293198d Compare October 20, 2026 12:25
@tee8z
tee8z self-requested a review October 20, 2026 12:34
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch from 293198d to 1b6d033 Compare October 20, 2026 13:01
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch from 1b6d033 to a42169d Compare October 20, 2026 15:17
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch from a42169d to 7c99bae Compare October 20, 2026 15:32

@tee8z tee8z left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One line repeats the auth_url_mismatch advice that #19 fixed; everything else matched the code (exit codes, quoted errors, anchors), and the changelog workflow and PR template look right. CRAP on 7c99bae: no function at or above 20, highest api::wait_for_payment at 19.24; the full test suite passed in the same run.

Comment thread docs/guides/troubleshooting.md Resolved
Comment thread src/cli.rs Resolved
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch from 7c99bae to 5b9f6b8 Compare October 20, 2026 16:12
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch from 5b9f6b8 to 574e085 Compare October 20, 2026 16:36
…, and a PR template

docs/guides/troubleshooting.md is keyed by exit code and by each
credential_problem name, with the fix for each; a test requires an entry for
every exit code and every CredentialProblem, which exhaustive matches keep
complete. docs/getting-started.md walks from install to a settled mutinynet
payment and a scripted receive.

CHANGELOG.md starts with the changes since 0.1.0. A Changelog workflow
fails a PR that changes src/cli.rs or api/commands.json without
CHANGELOG.md, unless it has the no-changelog label. AGENTS.md states the
rule and that the check is a heuristic. The pull request template asks for
the changelog entry, the verification gate, the review checks, the CRAP
result, and any check not run with its reason.

The docs example checks now also read CHANGELOG.md and the tutorial, so
their commands parse and their changes pass as offline dry runs.
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-troubleshooting branch from 574e085 to ffbf63c Compare October 20, 2026 16:51
@tee8z
tee8z self-requested a review October 20, 2026 16:52
@thebrandonlucas
thebrandonlucas merged commit 2f80ed0 into master Oct 20, 2026
7 checks passed
@thebrandonlucas
thebrandonlucas deleted the docs/cli-troubleshooting branch October 20, 2026 17:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

human review wanted CI passes; ready for a human reviewer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants