# Contributing to Runic Gateway — installer

Thanks for your interest in contributing! This repo is the **Runic Gateway
installer**: a single-binary Rust deployment tool that takes a stock ServUO
installation and configures it for Runic Gateway — overlay deployment, the
optional stock-file patch tier, uo-link installation and service registration,
version tracking, diagnostics, and updates.

It is a *deployment tool, not a hosted bootstrapper*. There is no `curl | bash`
and no installer service; artifacts are downloaded from a Gitea release page and
run by the operator.

By participating you agree to abide by our
[Code of Conduct](CODE_OF_CONDUCT.md).

## Status: planning

**No installer code exists yet.** The design of record is
[`docs/installer/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/PLAN.md)
in the docs repo — read it before opening a PR here. It defines the phases, the
locked decisions (Rust, unsigned releases, release-tarball plugin source,
published bundle manifest), and the Phase 0 prerequisites in other repos that
have to land first.

If you want to change *what the installer does*, propose it against the plan in
the docs repo first. If you want to change *how it does it*, a PR here is the
right place.

## Ways to contribute

- **Report a bug** or **request a feature** through the
  [issue tracker](https://gitea.whitlocktech.com/RunicGateway/installer/issues)
  (issue templates are provided).
- **Improve the code or docs** by opening a pull request (see below).
- **Never** report a security vulnerability in a public issue — see
  [SECURITY.md](SECURITY.md). The installer runs with elevated privileges, fetches
  remote artifacts, and handles the sidecar auth token, so its security matters.

## Development setup

**Prerequisites:** a recent stable Rust toolchain (install via
[rustup](https://rustup.rs/)).

Once the crate exists it will be a standard cargo project:

```bash
cargo build --release
cargo run -- --help
```

The installer targets **Linux and Windows** and is cross-compiled in CI, mirroring
the pattern in
[`link/.gitea/workflows/release.yml`](https://gitea.whitlocktech.com/RunicGateway/link/src/branch/main/.gitea/workflows/release.yml).
Please keep platform-specific code behind `#[cfg(...)]` rather than assuming one
OS, and test service registration on both where a change touches it.

### Testing against a real shard

Two things are hard to fake and easy to get wrong:

- **A successful file copy is not a working bridge.** ServUO's
  `ScriptCompiler.Compile()` ignores the build exit code and silently reloads the
  previous `Scripts.dll`, so a broken script build looks like a clean boot.
  Anything claiming success must verify *post-boot* state, not "files written".
- **The patch tier applies diffs to stock ServUO files.** Always dry-run
  (`git apply --check`) before applying, report per-patch, and degrade loudly —
  never silently — when a patch does not apply.

Prefer testing against a real ServUO tree and the real Rust sidecar over stubs.

### Checks

Please make sure the crate builds cleanly and is formatted and lint-clean before
opening a PR:

```bash
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release
```

## Branch & PR workflow

1. Branch from `main` with a descriptive name
   (`feature/…`, `fix/…`, `docs/…`, `chore/…`).
2. Keep changes focused; small PRs are easier to review.
3. Push and open a pull request against `main`. Fill out the PR template,
   including the **AI-assisted contributions** disclosure.
4. A maintainer will review; address feedback with follow-up commits.

### Commit messages

We use [Conventional Commits](https://www.conventionalcommits.org/) —
`type(scope): summary`. The release workflow derives versions from conventional
commits on `main`, so accurate `feat:` / `fix:` prefixes matter here.

## Keep the plan in sync

`docs/installer/` is canonical. A behavior change here — a new command, a changed
path, a different service definition, a change to the bundle manifest — is not
complete until the matching section of the plan (and, once it exists,
`docs/installer/INSTALL.md`) reflects it.

## AI-assisted contributions (disclosure required)

This project is developed openly with AI assistance, and we ask the same
transparency of everyone. **If you used an AI tool** (Claude, Copilot, ChatGPT,
Cursor, etc.) to help produce a contribution, you must disclose it:

- Tick the AI-usage box in the pull-request template and name the tool(s).
- Mark AI-authored commits with a trailer, e.g.
  `Co-Authored-By: Claude <noreply@anthropic.com>` or `Assisted-By: <tool>`.
- You remain responsible for every line you submit: review it, understand it,
  and make sure it is correct and that you have the right to contribute it.

Disclosed AI assistance is welcome. Undisclosed AI-generated contributions are
not, and may be closed.

## License

Runic Gateway is licensed under the **GNU General Public License v3.0 or later**
(see [LICENSE.md](LICENSE.md)). By submitting a contribution you agree that it is
licensed under the same terms (inbound = outbound) and that you have the right to
contribute it.