Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
5c5f7bc
[bfops/pr-authoring-guidance]: Guide PR authors toward reviewer-relev…
bfops Nov 18, 2026
998513c
[bfops/pr-authoring-guidance]: Package PR authoring guidance with gol…
bfops Nov 20, 2026
a638adc
[bfops/pr-authoring-guidance]: Keep golden answers out of PR-writing …
bfops Nov 20, 2026
b779079
[bfops/pr-authoring-guidance]: Recognize exercised workflows as behav…
bfops Nov 20, 2026
12bf216
[bfops/pr-authoring-guidance]: Distinguish the pre-PR baseline from l…
bfops Nov 20, 2026
3d71c97
[bfops/pr-authoring-guidance]: Show comparable evidence in both PR ex…
bfops Nov 20, 2026
4a68c1c
[bfops/pr-authoring-guidance]: Show complete generated sections when …
bfops Nov 20, 2026
ab982c9
[bfops/pr-authoring-guidance]: Lead PR Testing sections with the scop…
bfops Nov 20, 2026
91e96f5
[bfops/pr-authoring-guidance]: Keep before-and-after comparisons visi…
bfops Nov 20, 2026
26b34e5
[bfops/pr-authoring-guidance]: Describe each covered behavior in call…
bfops Nov 20, 2026
7b93b4a
[bfops/pr-authoring-guidance]: Use short test-case titles to describe…
bfops Nov 20, 2026
2b3e403
[bfops/pr-authoring-guidance]: Trim redundant parent detail from the …
bfops Nov 20, 2026
6c2fe7e
[bfops/pr-authoring-guidance]: Call out parent-scoped creation author…
bfops Nov 20, 2026
b32c25a
[bfops/pr-authoring-guidance]: Introduce test coverage and group case…
bfops Nov 20, 2026
6e7960a
[bfops/pr-authoring-guidance]: Keep reviewer wording when grouping te…
bfops Nov 20, 2026
3e9393a
[bfops/pr-authoring-guidance]: Match supplied golden bullets exactly
bfops Nov 20, 2026
3fc7f9f
[bfops/pr-authoring-guidance]: Calibrate PR testing summaries against…
bfops Nov 20, 2026
d26b42e
Merge remote-tracking branch 'origin/master' into bfops/pr-authoring-…
bfops Nov 21, 2026
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
45 changes: 45 additions & 0 deletions .agents/skills/write-pull-requests/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
name: write-pull-requests
description: Prepare verified commits and write or update GitHub pull request descriptions for SpacetimeDB.
---

# Writing pull requests

When preparing commits, use the signing requirements below. When drafting or editing a description, use the template and the writing guidance.

## Verified commits

Verified commits are required: a PR cannot be merged without them. Enable commit signing before creating commits for a PR, and ensure GitHub recognizes the commits as **Verified**. A local signature alone does not establish that GitHub can verify it.

If you cannot create verified commits, alert the user promptly, explicitly tell them that the PR cannot be merged without verified commits, and help them set up commit signing and GitHub verification. Do not silently proceed with unverified commits or present the PR as ready to merge. After setup, confirm that GitHub marks the PR's commits as **Verified**.

## Write for the reviewer

Use the [PR template](../../../.github/pull_request_template.md). Keep and complete every section, including the prescribed wording for inapplicable sections. Replace placeholders with facts from the change. Lead the description with what changes and why it matters. For a test-only PR, identify the behavior being protected. Reserve the evidence for Testing.

On an existing PR, work from the current body. Edit only the requested lines and preserve every section, the author's wording elsewhere, and the state of their checkboxes.

## Testing

Running the changed workflow on a representative input and inspecting its output is behavioral testing, including for changes to authoring instructions. Use the recorded output as evidence.

If no behavioral testing was performed, the entire Testing section is the single sentence “Not tested.” Reviewing the patch, checking whitespace, or verifying signatures alone counts as untested.

Summarize coverage at test-title granularity. For newly added tests, count the test functions, introduce them by number and kind alone with a colon, and give each one a plain bullet. Put the motivating regression first. Keep closely related tests adjacent. For existing coverage, identify what was exercised or updated.

Write each main bullet as a test title the caller would recognize. Name the option or operation when it defines the scenario. Use product verbs such as “uses the selected credit”; skip descriptions of how components pass values to one another. If one test also guards other independently breakable behaviors, put those on separate indented lines under its main case. A short parenthesis can group input forms. Preserve reviewer wording when regrouping.

For example, two billing tests might exercise eight assertions. The author also temporarily disabled duplicate detection, saw the first test fail, restored the change, and reran 96 tests. The complete Testing prose could be:

> Added two billing tests covering the following behaviors:
>
> - A duplicate invoice is rejected (CSV or JSON import). Disabling duplicate detection made the test fail.
> - Prepaid invoices use the selected credit. The same test covers:
> - Credits apply before tax.
> - Fully covered invoices skip payment.

Stop once the scope is clear. “Requires approval” is the entire permission test title; a second description of normal success or denial adds no new scope. Keep distinct extra coverage, such as *which* approval applies, under its own test. Give a specific error code when that is what the test distinguishes. For a failed mutation experiment, naming the removed protection and saying the test failed is enough. Keep fixture details, build settings, sample sizes and numeric thresholds in the test code unless they define the feature being tested. Omit response text, call ordering, suite status and restoration steps. A manual fault-injection result belongs on the regression bullet. Mention a failure or gap separately when it affects the conclusion.

For generated output, lead with what the trial covered. Show the complete comparison inline after the summary. Use a unified diff or two intact outputs for the unit under review. “Before” is the observed output from before the PR. Preserve that baseline. Label a later run on the base revision as a reproduction. Mention trial conditions that affect interpretation. If only one output was captured, show it and limit the claim to that observation.

For examples to use when refining this skill, see the [golden cases](examples/README.md).
66 changes: 66 additions & 0 deletions .agents/skills/write-pull-requests/examples/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Golden Testing sections

Use these cases to judge fresh drafts. Give the writer the case diff, raw evidence, and the instructions being tested. Keep this README and expected answers outside its workspace, including in the diff. For a change to the skill itself, supply a patch with example files excluded. Give the complete observed outputs so the writer has to choose the evidence.

Compare instructions on identical inputs and model settings. Reserve a separate case the author of the instructions did not tune against. Judge accuracy, evidence selection, and brevity; wording can vary. Add a diff, input notes, and a short example when a new case teaches a distinct decision.

## A change to PR-writing instructions

**Diff under review.** The authoring guide put behavior ahead of routine run details. The template changed its Testing prompt from “Describe any testing you've done” to “If untested, write only ‘Not tested.’ Otherwise, describe the behavior verified and any gap that affects confidence in this change.” See `git show 5c5f7bc0df` for the full historical patch.

**Trial input.** Two fresh agents drafted Testing sections for the same [database route test diff](https://github.com/clockworklabs/SpacetimeDB/compare/34dcbf8084cf07b978e9a1b9b14127a2fb24279d...5ef5f833a7a4e4230f0662f5e6d93990ba3e1d29). Both received the notes below. The original run did not record a model setting here. The revised run used Sol at low reasoning. The diff below covers both complete Testing sections.

**Example Testing section**

Fresh agents tried the skill on a regression-test PR. Other cases covered failed tests, untested changes, and edits to existing PR descriptions.

**Full comparison from the original drafting trial**


```diff
--- Before
+++ After
@@ -1,8 +1,10 @@
# Testing

-All 85 client API library tests passed with default features disabled. The new tests exercise the HTTP route with a mock backend. Live Cloud hierarchy behavior remains untested.
+New HTTP route tests cover these cases:

-- Create and update requests forward the expected parent to publication when `parent` is omitted, supplied by name, or supplied as a hex identity. Creation authorization receives the same parent, including when `clear=true` targets a missing database.
-- An unknown parent name returns 404 before backend publication for both creates and updates.
-- Resetting an existing database with either form of `parent` returns 400 and skips the backend reset, even with reset permission. Temporarily removing the parent guard made this test fail with 200.
-- Without `parent`, a denied reset returns 403 and skips the backend reset. An authorized reset calls the backend once and reports the existing database as updated.
+- Publishing to an existing database with `clear=true` and a parent returns HTTP 400 before calling the reset backend, whether the parent is supplied by name or identity. Manually removing the guard changed the response to HTTP 200 and failed the new test.
+- Clearing an existing database with no parent returns HTTP 403 without reset permission. With permission, the route calls reset once and reports the database as updated.
+- Creation and update forward the parent identity to publication when the request supplies a name or identity, and forward no parent when it is omitted. Creation also forwards the same value to authorization. A missing target follows the create path even with `clear=true`.
+- An unknown parent name returns HTTP 404 for both creation and update before calling the publication backend.
+
+The tests use a mock backend, so live Cloud hierarchy behavior remains unverified.
```


## Database route regression

**Input.** Same route diff as above. The tests used a mock backend. All 85 library tests passed. Manually removing the parent check changed the response from 400 to 200 and failed the new test. The guard was restored and the suite rerun.

**Editorial target for Testing**

Added four HTTP route tests covering the following behaviors:

- Publishing to an existing database with `clear=true` and a parent (supplied by name or identity). Removing the guard correctly failed the test.
- Clearing an existing database with no parent requires reset permission
- Create and update requests use the requested parent. The same test covers:
- Creation checks permission for the requested parent.
- Publishing with `clear=true` creates the database if it does not exist.
- An unknown parent name returns 404 for both creation and update

## Other regression cases

The notes below are offline test scenarios paired with real diffs. Example answers here are editorial targets.

| Diff and input notes | Example Testing text |
| --- | --- |
| [Rust receiver bindings](https://github.com/clockworklabs/SpacetimeDB/commit/98689d9e2f4a79a75d93b0bf5dadbefe4e5cea47). Codegen and CLI smoke tests passed. Bindings UI suite was not run. | The updated CLI smoke test reads the generated `mod.rs` and checks the receiver declarations. Codegen tests compare the emitted root with the checked-in fixture. The updated UI diagnostic paths remain unverified. |
| [CLI logout](https://github.com/clockworklabs/SpacetimeDB/commit/8756175d9df4f7a81e5e7647311c99772d365dd8). Only checked the diff and whitespace. | Not tested. |
| [React Native reconnect](https://github.com/clockworklabs/SpacetimeDB/commit/0863eb48cadcce3bdfa387435a5662b98ce850ee). New stubbed-globals test passed. In this scenario the cleanup test failed for an unknown reason. No device run. | The browser cleanup test left a visibility listener registered after disconnect. The cause is unknown. The new test established a connection with an empty window and no document. Device behavior remains unverified. |
| Same reconnect diff. Add the automated coverage to a body that already says `- [x] Browser smoke test completed by Nina.` and `- [ ] Try it on the loaner Android phone.` | Preserve both lines and their checkbox states. Add “A new test establishes a connection with no document and a window without DOM event methods.” |
77 changes: 0 additions & 77 deletions .agents/writing-prs.md

This file was deleted.

10 changes: 4 additions & 6 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Description of Changes

<!-- Please describe your change, mention any related tickets, and so on here. -->
<!-- What changes for users or maintainers, and why? Link related public issues where useful. -->

# API and ABI breaking changes

Expand Down Expand Up @@ -33,8 +33,6 @@ and what other components it interacts with in potentially concerning ways. -->

# Testing

<!-- Describe any testing you've done, and any testing you'd like your reviewers to do,
so that you're confident that all the changes work as expected! -->

- [ ] <!-- maybe a test you want to do -->
- [ ] <!-- maybe a test you want a reviewer to do, so they can check it off when they're satisfied. -->
<!-- If untested, write only “Not tested.”
Otherwise, summarize coverage in short test-case titles. Group additional behaviors beneath the test that covers them. Mention any important failure or gap.
Include a reviewer task only when a specific action is needed. -->
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,4 @@ These markers are provisional, and CI does not check any of this yet.

# Writing PRs

When creating or updating a PR, read [Writing pull requests](.agents/writing-prs.md). Follow its requirements for verified commits, preserving and faithfully completing every template section, and explaining verification and remaining uncertainty.
Use the [write-pull-requests skill](.agents/skills/write-pull-requests/SKILL.md) when preparing commits for a PR and when drafting or editing its GitHub description.
Loading