pragent-bot
60989cd72f
Specifies what counts as "tested" for this repo, the local test commands the bot treats as gates, and how pragent reads the repo config (`.pr-review.json` + static architecture.md from Nexus raw-hosted).
93 lines
3.5 KiB
Markdown
93 lines
3.5 KiB
Markdown
# 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. |