canalhandia/CONTRIBUTING.md

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

# 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.