Files

T

Claude ee20ab6ca4 docs(contributing): document interop suites and issue-template practice

2026-05-11 13:25:13 +00:00

18 KiB

Raw Blame History

Contributing to Amethyst

Thanks for your interest in improving Amethyst. This document captures the expectations, conventions, and review rules for code, documentation, and translation contributions across all modules in this repository (amethyst/, desktopApp/, quartz/, commons/, cli/, quic/, nestsClient/).

By contributing, you agree to license your work under the MIT license. Any work contributed where you are not the original author must contain its license header with the original author(s) and source.

Ways to contribute
Human and AI contributions
New contributor: proof of testing
Reporting bugs and requesting features
Security issues
Development setup
Project layout
Where code belongs (sharing philosophy)
Workflow
Coding standards
Tests
Interoperability tests
Commits
Pull requests
Translations
Releases

Ways to contribute

Fix bugs or implement features (see issues and the bounty notes in the issue templates).
Improve documentation in README.md, BUILDING.md, SECURITY.md, the per-module plans/ folders, and the .claude/ skill docs.
Add or improve translations on Crowdin.
Report bugs, suggest features, or open issues at github.com/vitorpamplona/amethyst/issues or the mirror at gitworkshop.dev/repo/amethyst.
Send patches over Nostr using GitStr — see the address at the bottom of the README.

Human and AI contributions

We accept pull requests authored by humans and pull requests authored with help from AI coding assistants (Claude Code, Copilot, Cursor, Codex, etc.). The rules are the same in both cases:

You are the author of record. You are responsible for understanding, testing, and defending every line of code in the PR — including code an assistant wrote for you. "The AI did it" is not a valid response to review feedback.
No hallucinated APIs or imports. Don't submit code that calls functions, classes, or libraries that don't exist in this repo or in our declared dependencies. Build and run it before you push.
Disclose AI involvement if it's substantial. If an assistant generated most of the diff, a one-line note in the PR description is appreciated (e.g. "Drafted with Claude Code, manually reviewed and tested"). This is a courtesy, not a gate.
No machine-translated locale files. Translations go through Crowdin so native speakers can review them.

New contributor: proof of testing

If this is your first PR to this repository, the PR description must include proof that you actually ran the change. This applies whether the patch was written by you or by an AI assistant.

What "proof" means:

Code/logic changes: paste the output of the relevant test run, the CLI command you ran, or the log lines that show the new behavior firing. Tests passing in CI is necessary but not sufficient — show the new path executing.
UI changes (any change to amethyst/, desktopApp/, or @Composable code in commons/): attach screenshots or a short screen recording of the new or changed screen on a real device or emulator. Include:
- Light and dark themes when the change is visible in both.
- The empty / loading / error states if your change introduces them.
- For Android: device model + Android version (e.g. "Pixel 7, Android 14").
- For Desktop: OS + window size (e.g. "macOS 14, 1440×900").
Build / Gradle / packaging changes: paste the ./gradlew command and the tail of its output, or the produced artifact name from desktopApp/build/compose/binaries/.
Translation-only PRs: screenshots are not required, but mention which locale and which strings you touched.

You don't need to keep doing this on every subsequent PR — once we've seen that you can run the project end-to-end, a short test plan in the PR description is enough. Maintainers may still ask for screenshots on visual changes regardless of contributor seniority.

If you cannot run a particular target locally (e.g. you don't have macOS but your change affects the DMG build), say so explicitly in the PR — don't claim it works when you haven't checked. Honest "I couldn't test this on Windows" is far better than a silent guess.

Reporting bugs and requesting features

We use GitHub issue templates at .github/ISSUE_TEMPLATE/. Please use them rather than opening a blank issue — they exist so triage can route the report without a follow-up round trip.

Bug report (`[BUG]` title prefix)

Required fields:

Describe the bug — one-paragraph summary of what's wrong.
To Reproduce — numbered steps (1, 2, 3, …) that walk a maintainer from a fresh app launch to the failure. "It crashes sometimes" is not a repro; "tap +, paste this nevent, tap Send" is.
Expected behavior — what should have happened.
Video and Screenshots — attach them whenever the bug is visual, involves navigation, or is timing-sensitive.
Device info — Phone Brand/Model, Android version, App version, App flavour (Google Play / F-Droid / Desktop), and Amber version if you sign with NIP-55.
Bounty (in Bitcoin sats) — see below.

Feature request (`[FEATURE]` title prefix)

Required fields:

Describe the solution you'd like — what the user-facing outcome is. Skip implementation suggestions unless they're load-bearing.
Bounty (in Bitcoin sats) — see below.

Bounties

Both templates include a bounty field, and the practice is unusually literal in this project: maintainer time is allocated by bounty size. The templates say so plainly — quoting them:

The size of the bounty is proportional to how much this matters to you. If no bounty is offered, not even a small one, this bug will not be worked on because it doesn't matter to you.

In practice:

Bug fixes and features are prioritized roughly by bounty ÷ effort.
Even a small bounty (a few hundred sats) outranks a zero-bounty issue.
Bounties are not refunded if you change your mind, so size them honestly against how much you want the outcome.
If you can fix the issue yourself, you don't need a bounty — open the PR. Bounties exist to move issues that nobody is currently working on.
Security issues do not need a bounty and should not be filed as public issues — see SECURITY.md.

Sending issues over Nostr

The repository is also mirrored at gitworkshop.dev/repo/amethyst for Nostr-native issue tracking, and patches can be sent via GitStr to the address at the bottom of the README.

Security issues

Do not file security vulnerabilities as public GitHub issues. Use GitHub private vulnerability reporting instead. See SECURITY.md for scope, expected response times, and the disclosure policy.

Development setup

Prerequisites:

JDK 21+ (Zulu or Temurin recommended)
Android Studio (for Android development)
Android 8.0+ phone or emulator (for installing the Android app)
Xcode + iOS simulator if you're touching quartz/ iOS code
libsodium for full local builds (brew install libsodium on macOS)

Desktop packaging prerequisites (only if you're building installers) are listed in BUILDING.md § Prerequisites.

Clone and import:

git clone https://github.com/vitorpamplona/amethyst.git
cd amethyst

Common Gradle entry points:

# Run desktop app
./gradlew :desktopApp:run

# Install Android debug build
./gradlew :amethyst:installDebug
# or specifically:
./gradlew installFdroidDebug
./gradlew installPlayDebug

# Build Quartz for all targets
./gradlew :quartz:build

# Full build (compiles all modules + runs tests)
./gradlew build

Project layout

quartz/         Nostr KMP library — protocol, crypto, models. No UI.
commons/        Shared Compose Multiplatform UI, icons, ViewModels, flows.
quic/           Pure-Kotlin QUIC v1 + HTTP/3 + WebTransport transport library.
nestsClient/    Audio-rooms client (NIP-53) built on :quic and :quartz.
amethyst/       Android app — Activity, layouts, navigation.
desktopApp/     Desktop JVM app — Window, sidebar, keyboard shortcuts.
cli/            `amy` — non-interactive JVM CLI over quartz + commons.
ammolite/       Legacy support module.

Per-module design docs live in <module>/plans/YYYY-MM-DD-<slug>.md. The global docs/plans/ folder is frozen — don't add new files there.

Before writing a new class or composable, check whether it already exists. Most logic is already implemented somewhere in the tree — duplicating it is the #1 cause of PR churn.

Place new code by purpose:

What you're adding	Goes in
Nostr event types, NIPs, tags, signing, crypto, Bech32	`quartz/commonMain/`
Shared Composables, icons, ViewModels, StateFlows	`commons/commonMain/viewmodels/` or `commons/commonMain/`
Android-only screen, navigation, system integration	`amethyst/`
Desktop-only window, sidebar, menu bar, shortcut	`desktopApp/`
`amy <verb>` subcommand (thin assembly only)	`cli/src/main/kotlin/.../cli/`
QUIC / HTTP/3 / WebTransport protocol code	`quic/`
MoQ session / audio-room logic	`nestsClient/`

Hard rules:

quartz/ has no UI.
cli/ has no Nostr protocol or business logic — it's a thin assembly layer over quartz + commons. If your CLI command needs new behavior, extract that behavior into commons/ first.
ViewModels are platform-agnostic and belong in commons/commonMain/. Only screens (the Composable that wires layout + navigation) stay in the platform module.
For platform-specific behavior in a shared file, use expect/actual — ask /kotlin-multiplatform if unsure.

Workflow

Survey first. Search the codebase for existing implementations before writing new code. The .claude/CLAUDE.md file has a recommended set of grep queries; running them takes a minute and routinely turns up the exact class you were about to re-invent.
Open a small PR. One feature or one fix per PR. Refactors that support the change are fine; unrelated refactors are not.
Branch off main.
Run tests + spotless locally before pushing (see below).
Open the PR with a description that explains why, not just what, and includes the proof-of-testing notes described above.

Coding standards

Kotlin, formatted with Spotless. Always run:
```
./gradlew spotlessApply
```
before considering a task complete. CI runs ./gradlew spotlessCheck and will fail on unformatted code.
Never use --no-verify to bypass pre-commit hooks. If a hook fails, fix the cause.
Don't add features, refactor, or introduce abstractions beyond what the task requires. A bug fix doesn't need surrounding cleanup.
Don't add error handling, fallbacks, or validation for scenarios that can't happen. Validate at system boundaries (user input, external APIs).
Prefer editing existing files to creating new ones. Don't create documentation files (*.md) unless asked or unless the change genuinely warrants one.
Default to writing no comments. Only add a comment when the why is non-obvious (a workaround, a subtle invariant, behavior that would surprise a reader). Don't restate what the code does.
Don't reference the current task, fix, or callers in comments (e.g. "added for issue #123") — that belongs in the PR description.

Tests

# Unit + KMP common tests across all modules
./gradlew test

# Android instrumented tests (needs device or emulator)
./gradlew connectedAndroidTest

# A single module
./gradlew :quartz:test
./gradlew :commons:test

Add tests when:

You fix a bug — a regression test that fails before your fix and passes after.
You add new protocol code in quartz/ — Nostr event parsing, NIP implementations, and crypto paths should have unit coverage.
You add anything to commons/ that has non-trivial state transitions.

UI changes don't need automated UI tests, but they do need the screenshots described in the proof-of-testing section.

Interoperability tests

Amethyst ships several cross-stack interop harnesses that drive our code against external reference implementations. They are not run in CI — they're slow, require Rust / bun / Docker / Chromium, and most PRs don't touch the code they cover. If your change does touch a covered area, you are expected to run the relevant suite locally and paste the result into the PR description. Reviewers may ask if you didn't.

Suite	Path	What it covers	When you must run it
Marmot / MLS (Whitenoise)	`cli/tests/marmot/`	NIP-EE MLS groups: KeyPackage publish, group create/invite/remove, admin promote/demote, leave, replay, KP rotation — Amethyst (or `amy`) ↔ `whitenoise-rs` Rust reference	Changes to MLS / Marmot code in `quartz/` or `commons/`, or to the Marmot UI / group-chat flow in `amethyst/`
NIP-17 DMs (amy ↔ amy)	`cli/tests/dm/`	Text + file DM round-trip, strict kind:10050, `--allow-fallback` NIP-65 chain, `dm list --since` window slide	Changes to DM, gift-wrap (NIP-59), or NIP-17 code paths in `quartz/` or `commons/`
Audio rooms (manual)	`cli/tests/nests/`	47-test manual harness: Amethyst Android ↔ nostrnests.com reference web client. Host/listener flows, hand-raise, role promotion, kicks, schedule, reconnect, JWT refresh, PIP	Changes to NIP-53 audio rooms (`amethyst/` UI) or `nestsClient/` that affect host/listener UX
MoQ-lite hang-tier	`nestsClient/tests/hang-interop/`	Rust `hang-listen` / `hang-publish` ↔ Amethyst Kotlin through a real `moq-relay` 0.10.x subprocess. Wire-byte capture, FFT-on-PCM, mute / hot-swap / packet-loss / late-join / 60s broadcast / multi-listener fan-out	Changes to `nestsClient/.../moq/lite/`, `nestsClient/.../audio/`, `MoqLiteSpeaker.kt` / `Listener.kt`, `ReconnectingNests*.kt`, or `quartz/.../nip53`
MoQ-lite browser-tier	`nestsClient/tests/browser-interop/`	Headless Chromium with `@moq/lite` + `@moq/hang` via Playwright ↔ Amethyst Kotlin (forward + reverse). WebCodecs encode/decode, ALPN negotiation, browser-side reconnect	Same as hang-tier, plus any change to `:quic` (WebTransport, packet header protection, key updates, stream demux)
QUIC interop-runner	`quic/interop/`	The standard `quic-interop-runner` matrix (ns-3 sim) against aioquic, picoquic, quic-go, quinn. Handshake, transfer, loss, corruption, IPv6, migration, key update, version negotiation	Any change in `:quic` that could affect wire bytes, congestion control, or the TLS state machine

Running them

Each suite has its own README with prerequisites and flags. Quick links:

Marmot, DM, audio-rooms (CLI): cli/tests/README.md. Headless variants require only cargo + a loopback nostr-rs-relay; the interactive Marmot variant additionally prompts the human to drive the Amethyst Android UI.
MoQ-lite hang + browser: nestsClient/tests/README.md. Opt-in via -DnestsHangInterop=true and/or -DnestsBrowserInterop=true on :nestsClient:jvmTest. Cold first run is ~10–13 min per tier; cached runs ~3–7 min.
QUIC interop-runner: quic/interop/ plus its plan at quic/interop/plans/2026-05-06-interop-runner.md. The standard sweep is for peer in aioquic picoquic quic-go quinn; do quic/interop/run-matrix.sh -s $peer; done. Always sequential — run-matrix.sh is not safe to invoke concurrently.

If a change is documentation-only, UI-only, build-script-only, or otherwise cannot affect wire bytes / decoded audio / MLS state / DM envelopes, skip the interop suites and say so in the PR description.

Use Conventional Commits: feat:, fix:, refactor:, docs:, chore:, test:, etc.
One logical change per commit. Squashing during PR review is fine.
Keep subject lines under ~72 characters. Use the body to explain why the change was made when it isn't obvious.
Branch names follow feat/<scope>-<short-name> or fix/<scope>-<short-name> (e.g. feat/desktop-sidebar-resize, fix/android-notification-leak).

Pull requests

A good PR description has:

Summary — 1–3 sentences on what changed and why.
Modules touched — quartz, commons, amethyst, desktopApp, cli, etc.
Test plan — exactly what you ran, on what platform, with what result. Include screenshots / recordings for UI changes (mandatory for first-time contributors; expected for all contributors on visual changes).
Risk / rollback — if the change touches relay subscriptions, the NostrClient, signing, or anything in Account/LocalCache, call out what could break and how to revert.

We aim to give first-pass feedback within a few days. PRs may sit longer if they're large, touch security-sensitive code, or arrive during a release window.

Translations

Submit translations via Crowdin, not as direct PRs to strings.xml. Crowdin pushes are integrated through the crowdin.yml workflow.
The /find-missing-translations skill can help reviewers spot untranslated keys for a target locale.

Releases

Release runbooks (Android AAB upload, desktop packaging on macOS / Windows / Linux, Homebrew cask, Winget manifest, Apple Developer signing, asset naming) live in BUILDING.md § Release runbook and BUILDING.md § Bootstrap runbook.

If your PR needs to be cut into a particular release, mention it in the PR description and the maintainers will coordinate.

Thanks again for contributing.

18 KiB Raw Blame History Unescape Escape