CONTRIBUTING.md

Rama main · réplica de lectura del repositorio original.

# Contributing to Aldus

Thanks for helping improve Aldus. It is public beta software, so focused bug fixes, documentation corrections, accessibility improvements, and reports from real self-hosted libraries are especially useful.

Keep changes small, preserve existing user data and installed-client behavior, and avoid adding dependencies or abstractions without a current requirement.

## Before contributing code

- Use [GitHub Discussions Q&A](https://github.com/Mahcks/Aldus/discussions/categories/q-a) for questions and setup help, and [Ideas](https://github.com/Mahcks/Aldus/discussions/categories/ideas) to explore an idea before it is ready for an issue.
- Use the [issue chooser](https://github.com/Mahcks/Aldus/issues/new/choose) for reproducible bugs, documentation problems, and concrete feature requests.
- Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md), never in a public issue or Discussion.

For a substantial change, open an issue or Discussion before investing in an implementation so the scope and compatibility impact can be agreed first. Small fixes can go directly to a focused pull request.

## Development setup

You need Go 1.26.6+, Bun 1.3.5+, Node.js LTS, `ffprobe`, and Docker for production-image work.

```sh
cd app && bun install && cd ..
make dev
```

The development server uses `.tools/alignment-venv/bin/python3` when that local Python environment exists, and stores alignment models in `.tools/alignment-models`. You can override the worker with `ALDUS_ALIGNMENT_COMMAND` and the model directory with `ALDUS_ALIGNMENT_MODEL_DIR`. Unlike the production alignment image, `make dev` does not install Python dependencies or download models. CPU alignment also requires PyTorch and WhisperX; their pinned dependencies are in the Dockerfile and `tools/requirements-alignment.txt`.

| Command | Does |
| --- | --- |
| `make server` | Run the Go server on port 8080 |
| `make dev-app` | Run the Expo development server |
| `make expo` | Run Metro for an installed native development client |
| `make ios` | Install dependencies, build, and install the iOS development client |
| `make dev-docs` | Run the Starlight documentation site |
| `make demo-media` | Fetch and verify the public-domain demo catalog |
| `make generate` | Regenerate sqlc and public TypeScript contracts |
| `make lint` | Run Go vet, formatting checks, and Expo lint |
| `make test` | Run Go, race, client, and TypeScript tests |
| `make build` | Build the production web app and Go server |
| `make docker` | Build the production container locally |

For an iPhone development build, first update the source checkout on your Mac, connect the phone, and run `make ios` from the repository root. It installs the locked dependencies, updates the native project and CocoaPods, then builds and installs the client. Keep `make expo` running to serve the development app. JavaScript-only changes normally need a reload; native dependencies, reader patches, and native configuration require `make ios` again. Updating the Docker image updates the server and web app separately.

The repository has four main parts:

- `server/` — Go API, SQLite migrations, media processing, and the production web server.
- `app/` — universal Expo web, iOS, and Android client.
- `tools/` — the external WhisperX alignment worker.
- `docs/` — the Astro Starlight site plus repository-only technical references.

The production image contains the Go server and exported Expo web app together. Do not introduce a second production service or image for ordinary application code.

## Frontend code map

Start with [app/src/README.md](app/src/README.md) to find the route, component, hook, or platform adapter you need. Screen components stay in Expo route files. Supporting code lives outside the route tree, grouped by purpose and product area.

## Contracts and generated code

Public JSON contracts live in `server/internal/api/contracts` and generate `app/src/generated/api.ts`. Stable SQL queries generate into `server/internal/database/sqlc`. Never edit either generated directory by hand; change its source and run:

```sh
make generate
```

See [docs/code-generation.md](docs/code-generation.md) for the boundaries between generated and handwritten code. Synchronization changes must also follow [docs/sync-architecture.md](docs/sync-architecture.md) and preserve the exact-progress acceptance fixtures.

API v1 is additions-only while a released client depends on it:

- Adding an endpoint or response field is compatible; the server may ship first.
- A new optional client feature must work when an older server does not provide it.
- Removing or renaming a field or route, changing its type or meaning, or changing authentication/status behavior requires a future `/api/v2` while v1 remains available.
- Current clients call `/api/v1`. `/api` remains a permanent v1 alias for already-installed clients.

## Validate a change

Run the checks that cover your change. Before submitting a broad server or client change, run:

```sh
make generate
make lint
make test
make build
git diff --check
```

Documentation changes should also pass:

```sh
cd docs && bun run build
```

Do not include generated build output, local databases, media, credentials, or release artifacts.

## Maintainer releases

Start with the read-only classifier:

```sh
make release-status VERSION=<server-version>
```

| Change | Command |
| --- | --- |
| Server, Docker, alignment, shared/web app | `make release VERSION=<server-version>` (container, demo, then docs) |
| Native or shared app | `make ios-testflight` after the referenced server is public |
| Both | Run the server phase, then the iOS phase |
| Docs only | Manually dispatch the Docs workflow |

The complete compatibility policy, preparation steps, phase checklist, recovery commands, and
physical-device gate are in [RELEASING.md](RELEASING.md).

## Continuous integration

CI runs on pushes to `main`, pull requests, and manual dispatches. Feature branches
without a pull request can be checked with a manual run. A newer push cancels
superseded validation for the same branch or pull request; manual runs and release
publication are not canceled by that policy.

Every main commit still runs the full validation suite. Releases require successful
CI for the exact candidate commit, even if a newer rerun is queued or canceled.
`make release-status` reports both the latest run state and whether the candidate
already has a successful run.

Go and Bun dependency downloads and the CPU, CUDA, and ARM64 image layers are
cached. Frozen-lockfile installs, tests, and image checks still run. Cache misses
are expected on the first run; compare warm runs before assessing speed gains.

The KOReader acceptance script starts Metro once for its web phases. Standalone
runs install dependencies as before; CI sets `ALDUS_ECOSYSTEM_SKIP_INSTALL=1`
after its own frozen-lockfile install. Shared Metro output is saved as `web.log`
in the acceptance artifact directory, with separate screenshots for each phase.