# 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](#ways-to-contribute) - [Human and AI contributions](#human-and-ai-contributions) - [New contributor: proof of testing](#new-contributor-proof-of-testing) - [Reporting bugs and requesting features](#reporting-bugs-and-requesting-features) - [Security issues](#security-issues) - [Development setup](#development-setup) - [Project layout](#project-layout) - [Where code belongs (sharing philosophy)](#where-code-belongs-sharing-philosophy) - [Workflow](#workflow) - [Coding standards](#coding-standards) - [Tests](#tests) - [Interoperability tests](#interoperability-tests) - [Commits](#commits) - [Pull requests](#pull-requests) - [Translations](#translations) - [Releases](#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](https://crowdin.com/project/amethyst-social). - Report bugs, suggest features, or open issues at [github.com/vitorpamplona/amethyst/issues](https://github.com/vitorpamplona/amethyst/issues) or the mirror at [gitworkshop.dev/repo/amethyst](https://gitworkshop.dev/repo/amethyst). - Send patches over Nostr using [GitStr](https://github.com/fiatjaf/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/`](.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](SECURITY.md). ### Sending issues over Nostr The repository is also mirrored at [`gitworkshop.dev/repo/amethyst`](https://gitworkshop.dev/repo/amethyst) for Nostr-native issue tracking, and patches can be sent via [GitStr](https://github.com/fiatjaf/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](https://github.com/vitorpamplona/amethyst/security/advisories/new) instead. See [SECURITY.md](SECURITY.md) for scope, expected response times, and the disclosure policy. ## Development setup Prerequisites: 1. **JDK 21+** (Zulu or Temurin recommended) 2. **Android Studio** (for Android development) 3. **Android 8.0+ phone or emulator** (for installing the Android app) 4. **Xcode + iOS simulator** if you're touching `quartz/` iOS code 5. **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](BUILDING.md#prerequisites). Clone and import: ```bash git clone https://github.com/vitorpamplona/amethyst.git cd amethyst ``` Common Gradle entry points: ```bash # 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 `/plans/YYYY-MM-DD-.md`. The global `docs/plans/` folder is frozen — don't add new files there. ## Where code belongs (sharing philosophy) 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 ` 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 1. **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. 2. **Open a small PR.** One feature or one fix per PR. Refactors that support the change are fine; unrelated refactors are not. 3. **Branch off `main`.** 4. **Run tests + spotless locally** before pushing (see below). 5. **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: ```bash ./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 ```bash # 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/`, `MoqLite*Speaker.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`](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`](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/`](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](https://www.conventionalcommits.org/): `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/-` or `fix/-` (e.g. `feat/desktop-sidebar-resize`, `fix/android-notification-leak`). ## Pull requests A good PR description has: 1. **Summary** — 1–3 sentences on what changed and why. 2. **Modules touched** — `quartz`, `commons`, `amethyst`, `desktopApp`, `cli`, etc. 3. **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). 4. **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](https://crowdin.com/project/amethyst-social), 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](BUILDING.md#release-runbook) and [BUILDING.md § Bootstrap runbook](BUILDING.md#bootstrap-runbook-one-time). 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.