# Contributing — Canalhandia (Canalhandia Minecraft plugin)

Canalhandia is a Minecraft Paper plugin that adds PT-BR chat games, item
protection, and other in-game commands for the Canalhandia server. This repo
holds the plugin source. The companion server config lives at
`gitea_admin/canalhandia-config`.

## Before you open a PR

1. **Fill in the PR template** (`.gitea/pull_request_template.md`). The
   *Risk* checklist is the part pragent scores you on — check the boxes that
   apply, delete the ones that don't.
2. **Update the static context** if your change introduces new house rules.
   See `## Adding house rules` below.
3. **Run the gates locally** (see *Test commands*). CI is a single
   `mvn -B test` against JDK 25 — there's no other infra in this repo.

## Test commands

```bash
# Run the test suite (JDK 25 required). Same command CI uses:
mvn -B test

# Compile only (faster):
mvn -B -DskipTests package

# Integration: copy the resulting jar into a test Paper server's plugins/
# directory, start the server, exercise the affected commands. The chat
# and stats paths are NOT covered by unit tests — they need a live server.
```

### What counts as "tested"

For pragent (and reviewers) to consider a change tested, the PR must show:

- [ ] `mvn -B test` output from your machine pasted in the PR, **OR** a CI
      run URL.
- [ ] A new behaviour has a JUnit test in `src/test/java/...` that exercises
      the new code path. New `comando:` blocks need at least one test that
      sends a fake event and asserts the message format.
- [ ] If the change touches the chat immutability rule, the singular-form
      rule, or the Bedrock fallback, a manual test on a Paper server is
      required **and** a one-line note pasted in the PR.
- [ ] If the change touches `<world>/players/stats`, you must show the
      file path on a running server (`ls <world>/players/stats/*.json`)
      and confirm the stats file is updated, not the wrong path.

### Out of scope for tests

- Performance / load tests (none in this repo).
- E2E against the live server (manual; verify in `canalhandia-config` repo).
- UI / browser tests (no web surface).

## Commit messages

Conventional commits. Examples:

- `feat: add per-player cobblestone counter command`
- `fix(void): keep inventory when dying in lava void`
- `docs: update README build instructions`
- `chore: bump pom parent to 1.4.2`

## Branch names

`<type>/<short-kebab-description>` matching commit type. Example:
`fix/void-keep-inventory`.

## PR review

- The bot (`pragent`) reviews every PR labelled `AI-REVIEW`. It reads
  `.pr-review.json` from `main` + the static `architecture.md` from Nexus
  raw-hosted. Adding a new house rule? Update both.
- Add the `AI-USAGE` label if you want the bot to also post a token /
  cost-equivalent report on the review.

## Adding house rules

If your PR changes how translatable components behave, how chat edits work,
how stats are read, or how the Bedrock fallback is rendered, you must:

1. Update the relevant section in the static `architecture.md` (upload a new
   copy to Nexus raw-hosted at `canalhandia/architecture.md`).
2. Bump `.pr-review.json:instructions` with a one-paragraph summary.
3. Add a finding-checklist item to `.gitea/pull_request_template.md` *Risk*
   section so PR authors know to confirm the rule.

Bot does not detect house-rule drift automatically — these three updates
together are the maintainer contract.

## Rollback

A single PR that bumps the plugin jar in `canalhandia-config` rolls back.
Plugins are jar-swapped, no migrations.