Skip to content

docs: add a staging setup and a Try it section for each PR #97

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
thebrandonlucas wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

docs: add a staging setup and a Try it section for each PR #97

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,22 @@
<!-- What changed for users, and why. Name the base PR if this is stacked. -->

## Try it on staging

<!-- See AGENTS.md "Try it on staging". Commands a reviewer pastes after the setup. -->

Setup: [Try a pull request on staging](docs/development.md#try-a-pull-request-on-staging)

```sh
voltage ...
```

Expect: ...

## Checks

- [ ] User-visible change: a guide or reference under `docs/` and `CHANGELOG.md` (**Unreleased**) are updated, or the PR has the `no-changelog` label.
- [ ] The verification gate in `docs/development.md` passes.
- [ ] The diff was reviewed against its base with the `voltage-pr-review` skill, and every new error and early-return path has a test.
- [ ] CRAP report, when `src/` or `tests/` changed: the highest score and each function at or above 20.
- [ ] Checks not run, and why:
- [ ] **Try it on staging** lists every changed `--help` and docs example, with what to expect.
25 changes: 25 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,31 @@ so a pull request is not ready until each one is done and reported.
5. In the pull request description, give the checks you ran and the CRAP result: the
highest score and each function at or above 20. Name any check you could not run, and
why.
6. In the pull request description, add a **Try it on staging** section that a reviewer can
paste after the [staging setup](docs/development.md#try-a-pull-request-on-staging).
See [Try it on staging](#try-it-on-staging).

## Try it on staging

The section tells a reviewer exactly what to run and what to look for. Write it for a
reviewer who is on the branch and has run the setup, and nothing else:

- Start with one line: `Setup: [Try a pull request on staging](docs/development.md#try-a-pull-request-on-staging)`.
- Give the commands in `sh` blocks, ready to paste. Use `voltage` (the staging alias) and
`--account me`, never a profile the reviewer may not have. Use a placeholder only for a
value each reviewer has to supply, such as `WALLET_ID`, and say how to find it, such as
`voltage wallets list --account me`.
- After each command or group, say what to expect in one line: the text, symbol, color, or
exit code that shows the change works.
- List every `--help` and docs example that the pull request adds or changes, adapted to the
setup. To find them, run
`git diff origin/master...HEAD -- README.md docs src | grep '^+.*voltage '`.
- Cover the variants the change affects, such as piped output (`2>&1 | cat`), `--json`,
`--quiet`, `--color never`, or `--no-input`.
- Mark each command that sends a change. It needs `--execute` and a test-network wallet;
say so.
- For a change with nothing to see, such as a refactor or a test-only change, write
`Nothing to try on staging` and the reason.

A reviewer runs the CRAP report on the pull request's head and reports each violation as a
finding, together with the review from step 1.
Comment on lines +39 to 63

@tee8z tee8z Oct 26, 2026

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.

The new ## Try it on staging heading comes before the paragraph "A reviewer runs the CRAP report…". That paragraph now sits under the staging section, though it belongs to Before you request review. This suggestion moves the section below the paragraph:

Suggested change
## Try it on staging
The section tells a reviewer exactly what to run and what to look for. Write it for a
reviewer who is on the branch and has run the setup, and nothing else:
- Start with one line: `Setup: [Try a pull request on staging](docs/development.md#try-a-pull-request-on-staging)`.
- Give the commands in `sh` blocks, ready to paste. Use `voltage` (the staging alias) and
`--account me`, never a profile the reviewer may not have. Use a placeholder only for a
value each reviewer has to supply, such as `WALLET_ID`, and say how to find it, such as
`voltage wallets list --account me`.
- After each command or group, say what to expect in one line: the text, symbol, color, or
exit code that shows the change works.
- List every `--help` and docs example that the pull request adds or changes, adapted to the
setup. To find them, run
`git diff origin/master...HEAD -- README.md docs src | grep '^+.*voltage '`.
- Cover the variants the change affects, such as piped output (`2>&1 | cat`), `--json`,
`--quiet`, `--color never`, or `--no-input`.
- Mark each command that sends a change. It needs `--execute` and a test-network wallet;
say so.
- For a change with nothing to see, such as a refactor or a test-only change, write
`Nothing to try on staging` and the reason.
A reviewer runs the CRAP report on the pull request's head and reports each violation as a
finding, together with the review from step 1.
A reviewer runs the CRAP report on the pull request's head and reports each violation as a
finding, together with the review from step 1.
## Try it on staging
The section tells a reviewer exactly what to run and what to look for. Write it for a
reviewer who is on the branch and has run the setup, and nothing else:
- Start with one line: `Setup: [Try a pull request on staging](docs/development.md#try-a-pull-request-on-staging)`.
- Give the commands in `sh` blocks, ready to paste. Use `voltage` (the staging alias) and
`--account me`, never a profile the reviewer may not have. Use a placeholder only for a
value each reviewer has to supply, such as `WALLET_ID`, and say how to find it, such as
`voltage wallets list --account me`.
- After each command or group, say what to expect in one line: the text, symbol, color, or
exit code that shows the change works.
- List every `--help` and docs example that the pull request adds or changes, adapted to the
setup. To find them, run
`git diff origin/master...HEAD -- README.md docs src | grep '^+.*voltage '`.
- Cover the variants the change affects, such as piped output (`2>&1 | cat`), `--json`,
`--quiet`, `--color never`, or `--no-input`.
- Mark each command that sends a change. It needs `--execute` and a test-network wallet;
say so.
- For a change with nothing to see, such as a refactor or a test-only change, write
`Nothing to try on staging` and the reason.

Expand Down
14 changes: 14 additions & 0 deletions docs/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,20 @@ command line. A profile ignores `VOLTAGE_WALLET_ID` and the other ambient variab
`--wallet` explicitly. Confirm a wallet's reported network is a test network before creating
a payment. Browser login needs the device-login release deployed on the staging auth service.

### Try a pull request on staging

To check a pull request's change by hand, check out its branch, with `.env` filled in as in
step 1 above, and paste this from the repository root:

```sh
alias voltage="$PWD/scripts/voltage-staging"
voltage --build
voltage login --account me --credential-store file
```

Then run the commands in the pull request's **Try it on staging** section; they assume this
setup. After pulling new commits, run `voltage --build` again.

## Staging acceptance

Complete these steps against the deployed staging services before publishing a release, and
Expand Down
Loading