Claude
4eae92964e
Cut the doc from 411 to ~75 lines. The performance, coroutine, caching, logging and KMP rules already live in CLAUDE.md and the skills that agents load, so they are dropped here. The doc now leads with one rule: no PR is opened until a human has reviewed the diff and tested the app by hand on a device, and an agent never opens the PR itself. CONTRIBUTING.md, the PR template and CLAUDE.md now point to that rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DbNeTtN2RpXHeGwNzPfvbQ
3.3 KiB
Contributing to Amethyst with AI Assistance
This adds to CONTRIBUTING.md, which covers every
contribution. It applies to any PR where an AI coding assistant (Claude
Code, Copilot, Cursor, Codex, etc.) wrote a large part of the diff.
The rule: a human reviews and tests before any PR is opened
No PR, GitHub or nostr proposal, may be opened until a human has:
- Read and understood the whole diff. You are the author of record. You must be able to explain and defend every line in review.
- Tested the app by hand on a real device or emulator. Install a build that includes the change, run the new flow, and check that the things it touches still work. Passing tests and green CI do not count as manual testing.
AI agents: you must not open, publish or submit a PR yourself. When the code is ready, stop. Give the human the branch, a summary of what changed, and a test plan they can follow on a device. They open the PR after they have done both steps above. Drafting the PR description for them is fine. Do not write "tested on device" unless the human has told you they did it.
PRs that skip these steps will be closed.
Before writing code
- Check the issue is still wanted. Make sure it is still open, not already fixed by a merged PR, and not out of scope. Old bounty issues often fail this check. Search open and closed PRs for an earlier attempt.
- Ask first for sensitive areas. Open an issue and get a maintainer
to agree before changing any of these:
- signers and key storage (
NostrSigner*, KeyStore); - the release pipeline (
.github/workflows/, signing, Gradle plugins, packaging); - how Amethyst reads a NIP, or a new kind or tag.
- signers and key storage (
- Make sure it fits a decentralised client. No central server, no state controlled by the maintainers, no required third-party account.
What the PR must include
Put these in the Test plan section of the PR template:
- What the human tested on a device: device model, Android version, the steps taken and what happened. Add screenshots or a recording for UI changes.
- Regression checks: which existing screens or flows the change could break, and how each one was checked. If one could not be checked, say so and explain why.
- Both flavours if the change could differ between them (UI,
services, dependencies, manifest, ProGuard):
./gradlew installPlayDebugand./gradlew installFdroidDebug. F-Droid has no Google-only libraries. - The minified build (
./gradlew :amethyst:installPlayBenchmark) if the change touches reflection: ViewModel factories, serialization,expect/actual. - Automated tests for new logic in
quartz/orcommons/, and a regression test for every bug fix. Run any interop suite the change touches (seeCONTRIBUTING.md§ Interoperability tests). CI does not run them. - For protocol changes (a new kind, tag or reading of a NIP): quote
the NIP line that allows it, paste the published event as fetched back
from a relay (
nak req -i <id> wss://<relay>), and say which other clients and older Amethyst versions understand it.
If testing on the device finds bugs, fix them in separate commits whose messages name the root cause. Don't squash them into the feature commit.