Skip to content

Free open-source image editor for the browser

Keep tests and review evidence proportional to changes (#26)

Rodrigo Belfiore7598c429bed1
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 3a41ff9..6da49a2 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,5 +1,5 @@
<!-- Include evidence when opening the PR. Keep the description brief and direct;
-link detailed reports, raw data and reproduction steps. Omit work logs. -->
+use PR/CI attachments for generated evidence instead of committing it. Omit work logs. -->
## Change
@@ -8,7 +8,7 @@ Add only the implementation details or tradeoffs needed to review the change. --
## Validation
-<!-- Report the four required checks from README.md and any verification gaps. -->
+<!-- Report the required checks from AGENTS.md and any verification gaps. -->
## Visual evidence
@@ -17,7 +17,7 @@ visible in context for visual approval. Show before/after for existing UI change
and representative states for new UI. Rendered output alone is insufficient.
Rendering changes: also show before/after output side by side, using the same
fixture and matching conditions; name the settings and state what varies.
-Include relevant quality metrics when a reference or expected property exists;
+Include quality metrics for a concrete quality claim or regression;
state units and limits. Keep image-quality results separate from timings.
Nonvisual code changes: show the exercised workflow. Verify that image links
are accessible from this description. Documentation-only changes may mark
@@ -27,6 +27,6 @@ this section not applicable. -->
<!-- Use a compact results table following PERFORMANCE.md: reproducible base/head
comparison, workload and environment, timing scope, sample counts, median/p95,
-and a short interpretation. Link full measurements and reproduction steps.
+and a short interpretation. Include the reproduction command; link extra samples when useful.
Separate neutral/bypass overhead from the cost of new active behavior.
If rendering work is unaffected, explain why. Report missing evidence explicitly. -->
diff --git a/AGENTS.md b/AGENTS.md
index f8db122..362513a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -7,7 +7,7 @@ Write committed code, comments, documentation, and UI text in English. Use [CONT
## Simplicity
- Give each module, function, and component one coherent responsibility. Entry points compose; resource owners manage their own lifecycles.
-- Judge simplicity across the complete operation, including callers and cleanup. Moving lines into forwarding helpers does not simplify it. Keep cohesive work together; use no arbitrary file-size limits.
+- Judge simplicity across the whole change, including callers, cleanup, tests, helpers, scripts, and documentation. Remove unnecessary work rather than compressing syntax or adding forwarding helpers. Keep cohesive work together; use no arbitrary line-count limits.
- Start with direct functions and library calls. Add abstractions, dependencies, validation, scheduling, or caching for a current requirement. Prefer a few repeated lines over coupling unrelated behavior.
- Extract a component when a region owns distinct state, refs, or behavior. Keep helpers local unless they have a separate responsibility or a real shared use. Define functions above their consumers.
- Keep control flow linear: guard clauses, braces, and `const` by default. Avoid nested ternaries and dense logic in JSX; use early returns or components for meaningful branches.
@@ -57,20 +57,20 @@ Keep Tailwind classes inline. Reuse presentation through components or repeat cl
## Tests and completion
-Prefer a few broad integration tests for features. Core algorithms also merit focused unit tests, especially rendering order, branch/merge connections, and resource reuse. Use Bun and real application modules with `vgpu/mock` for document, history, loader, and renderer orchestration. The mock does not execute shaders. Use Playwright for GPU pixels, browser interaction, and real format fixtures.
+For routine feature changes, prefer one short integration scenario that follows how a user would verify the change. For editing changes, load a suitable fixture, apply the operation, check the result, change a parameter, and undo. Reuse existing fixtures, helpers, and editing steps. Add cases for distinct failure modes or regressions; avoid repeating coverage of shared controls and history for each feature.
-Extend the main editing session with named steps for controls, preview, histogram, undo/redo, and export. Steps may live in separate modules. Keep independent rendering and loading checks separate. Assert known pixel values with appropriate tolerances; changed state or screenshots alone do not establish rendering correctness.
+Check meaningful output using a few representative samples, expected relationships, and tolerances. Assert rendered results when processing changes; state changes alone do not prove the effect works. Detailed numerical references and exhaustive parameter matrices need a concrete accuracy requirement or regression.
-Maintain the semantic [control API](API.md) for local, CI, and remote use. Exercise UI behavior through the DOM. Wait for observable results; avoid production completion tracking added only for tests. Test the behavior being changed rather than forcing every feature through the same test structure.
+Core algorithms also merit focused unit tests, especially rendering order, branch/merge connections, and resource reuse. Use Bun and real application modules with `vgpu/mock` for engine orchestration; the mock does not execute shaders. Use Playwright for rendered pixels, DOM interaction, and real format fixtures. Maintain the semantic [control API](API.md) for local, CI, and remote use. Wait for observable results; avoid production completion tracking added only for tests.
-Run `bun run check`, `bun run build`, `bun run test`, and `bun run test:browser` after changes and before a commit. Browser setup and focused commands are in [README.md](README.md#validation).
+For code changes, run `bun run check`, `bun run build`, `bun run test`, and `bun run test:browser` before a commit. Browser setup and focused commands are in [README.md](README.md#validation). For documentation-only changes, check the diff and affected references.
-Prepare evidence during implementation and include it in the initial PR description, using the [PR template](.github/pull_request_template.md). Lead with the problem and resulting behavior. Keep prose short, use compact comparison tables, and link detailed reports, raw data, and reproduction steps. Omit work logs and repeated explanations.
+Prepare evidence during implementation and include it in the initial PR description, using the [PR template](.github/pull_request_template.md). Lead with the problem and resulting behavior. Keep prose short and use compact comparison tables. Generated screenshots, logs, reports, and benchmark samples belong in ignored output directories and PR/CI attachments, not in Git. Commit test fixtures when maintained tests need them. Omit work logs and repeated explanations.
Every code PR includes actual application screenshots or rendered output demonstrating the result. UI additions or changes require screenshots of the affected interface in context, with the new or changed controls visible for visual approval; rendered output alone is insufficient. Show before/after for changes to existing UI or image output, representative states for new UI, and the affected workflow for nonvisual code changes. Compare the same fixture under matching conditions and state what varies. Embed accessible images in the description, name the fixture and settings, and verify the published links. Documentation-only changes may mark visual evidence not applicable.
-For processing changes, include relevant quality measurements when a reference or expected property is available. State the metric, units, and limits; do not generalize from synthetic fixtures to real photos. Keep quality results separate from rendering timings.
+Use image-quality metrics for a concrete quality claim or regression; ordinary correctness can use representative output checks. State metric units and limits, and do not generalize from synthetic fixtures to real photos. Keep quality results separate from rendering timings.
Assess performance on every code change; changes affecting GPU work require reproducible before/after evidence under [PERFORMANCE.md](PERFORMANCE.md). Report unavailable checks and measurements as verification gaps.
-Keep documentation close to its purpose and link rather than duplicate rules. Describe existing APIs accurately and label unimplemented designs explicitly.
+Update existing documentation for changed contracts or shared workflows; a feature does not need a separate guide. Link rules instead of duplicating them. Keep setup instructions portable; host-specific paths and workarounds stay outside the repository. Describe existing APIs accurately and label unimplemented designs explicitly.
diff --git a/PERFORMANCE.md b/PERFORMANCE.md
index ea88d53..d343a08 100644
--- a/PERFORMANCE.md
+++ b/PERFORMANCE.md
@@ -31,4 +31,4 @@ The [benchmark](tests/rendering-benchmark.ts) measures uninstrumented repeated r
Fused shader operations share a pass duration; they are not individually timed. Compute dispatches and opaque package operations need supported instrumentation before claiming GPU timing coverage. Editing must work when profiling is unavailable.
-Include reproducible results and their interpretation in the PR. An isolated benchmark explains cost; the complete workload establishes application impact. An environment failure is a verification gap, not evidence of unchanged performance.
+Reuse the existing [benchmark](tests/rendering.bench.ts) and timing helpers for the affected workload. An isolated benchmark explains cost; the complete workload establishes application impact. Summarize reproducible results and their interpretation in the PR; follow the [evidence rules](AGENTS.md#tests-and-completion) for detailed artifacts. An environment failure is a verification gap, not evidence of unchanged performance.
diff --git a/README.md b/README.md
index e3458a1..3b9671d 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ If the environment blocks local ports or browser processes, use its permitted ex
| `bun run test` | Browser-free integration and core unit tests using real modules and `vgpu/mock`. |
| `bun run test:browser` | GPU pixels, UI, and codec integration in Chromium. |
-Run all four after changes and before committing. [CI](.github/workflows/ci.yml) currently checks formatting/lint, Bun tests, and the build; it does not run browser tests.
+Run all four for code changes before committing. [CI](.github/workflows/ci.yml) currently checks formatting/lint, Bun tests, and the build; it does not run browser tests.
During development, select an existing test by path:
@@ -56,7 +56,7 @@ bun run test tests/renderer.test.ts
bun run test:browser tests/rendering.e2e.ts --workers=1
```
-One browser worker reduces CPU contention with SwiftShader. The mock does not execute shaders; use browser tests to check actual pixels. Reuse [browser fixtures](tests/fixtures.ts) and [image readers](tests/images.ts), and extend the [editing session](tests/editing.e2e.ts) for UI workflows.
+One browser worker reduces CPU contention with SwiftShader. The mock does not execute shaders; use browser tests to check actual pixels. Reuse [browser fixtures](tests/fixtures.ts), [image readers](tests/images.ts), and existing [editing steps](tests/editing.e2e.ts). Follow the [testing guidance](AGENTS.md#tests-and-completion) to keep coverage proportional to the change.
### Rendering benchmarks
diff --git a/REVIEW.md b/REVIEW.md
index e03e46c..61ea7f6 100644
--- a/REVIEW.md
+++ b/REVIEW.md
@@ -5,10 +5,11 @@ Use [AGENTS.md](AGENTS.md) for architecture and coding rules. Review the complet
## Review questions
- **Ownership:** Does each module have one responsibility? Does feature behavior stay with its feature? Is shared code independent of its consumers? `lib/` must meet the layer-0 definition, not merely have multiple callers.
-- **Simplicity:** Does an abstraction reduce the work of understanding callers and lifecycles? Could a direct function or a few repeated lines be clearer? Avoid extra configuration, forwarding layers, and speculative extension points.
+- **Simplicity:** Does the whole change justify its code, including tests, helpers, scripts, and documentation? Could direct functions or a few repeated lines replace configuration, forwarding layers, or speculative extension points?
- **State and boundaries:** Is each fact stored once? Are inputs and dependencies explicit, invalid states represented clearly, and external data validated at its boundary? Do errors retain enough context to fix them?
- **Behavior and lifetime:** Do edits, grouping, cancellation, and undo work together? Can asynchronous work outlive or overwrite its document? Does each owner release resources, subscriptions, and pending work correctly?
-- **Evidence:** Do tests check actual behavior and pixels where relevant? Can reviewers assess every new or changed UI from actual screenshots with the affected controls visible? Rendered output does not replace UI screenshots. Does the PR include [rendering measurements](PERFORMANCE.md) when GPU work changes? Check reported limitations as well as passing results.
+- **Tests:** Would a short, representative workflow fail if the changed behavior broke? Do extra cases protect distinct risks? Follow the [testing guidance](AGENTS.md#tests-and-completion).
+- **Evidence:** Can reviewers assess every new or changed UI from actual screenshots with the affected controls visible? Rendered output does not replace UI screenshots. Does the PR include [rendering measurements](PERFORMANCE.md) when GPU work changes? Check reported limitations as well as passing results.
## Findings and tradeoffs