88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# Contributing to Metropolis
|
|
|
|
This is the single onboarding entry point for new contributors. Shared rules
|
|
for people and coding agents are in [AGENTS.md](AGENTS.md); read them before
|
|
editing, especially the scraper-metadata preservation and operational-safety
|
|
rules.
|
|
|
|
## First Contribution
|
|
|
|
1. Read [README.md](README.md) for supported server versions, installation,
|
|
configuration, and commands.
|
|
2. Trace the relevant implementation using the source map below and check
|
|
nearby tests before changing behavior.
|
|
3. Make a focused change. Add or update automated tests for behavior changes;
|
|
update the manual pre-release checklist for behavior that needs a real
|
|
server.
|
|
4. Run `./gradlew test` and `./gradlew build`. Report any manual scenarios that
|
|
were not run rather than describing them as passing.
|
|
5. Update user-facing descriptions if setup, supported versions, commands,
|
|
dependencies, or behavior changed.
|
|
|
|
## Architecture and Source Map
|
|
|
|
- `MetropolisPlugin` loads configuration, connects Bukkit to WorldGuard and
|
|
WorldEdit, allocates plots, generates blocks, and manages regions.
|
|
- `Plot`, `PlayerHome`, grid/layout/support classes, and home stores implement
|
|
plot geometry, region ownership, allocation, and selected-home persistence.
|
|
- `commands/` contains the command handlers; `eventlisteners/` contains join
|
|
behavior.
|
|
- `src/main/resources/plugin.yml` declares dependencies, commands, and command
|
|
permissions. `config.yml` is the bundled configuration template.
|
|
- `src/test/` contains isolated JUnit/Mockito tests. `src/integrationTest/`
|
|
contains the opt-in tests that require a running server and RCON.
|
|
- `build.gradle` defines dependencies, Java/Gradle versions, formatting, and
|
|
test tasks. `.github/workflows/gradle.yml` runs tests and builds on pushes
|
|
and pull requests to `develop`.
|
|
|
|
## Prerequisites and Checks
|
|
|
|
- JDK 25. The Gradle wrapper uses Gradle 9.8 and can download the required
|
|
Gradle distribution; dependencies resolve from Maven Central, PaperMC, and
|
|
EngineHub.
|
|
- `./gradlew test` runs server-free JUnit tests.
|
|
- `./gradlew build` runs the normal build and verification lifecycle. The
|
|
plugin jar is written under `build/libs/`.
|
|
- CI compiles against Paper API 26.2, runs `test`, then builds. It does not
|
|
start a Minecraft server or run `integrationTest`.
|
|
|
|
The opt-in `integrationTest` source set currently has two tests: checking that
|
|
Metropolis appears in `/plugins`, and creating a coordinate reservation then
|
|
checking WorldGuard's `regions.yml`. It mutates the configured server's
|
|
WorldGuard data and needs a running Paper server with RCON, WorldGuard, and
|
|
WorldEdit. Use a disposable server, bind RCON to a trusted interface, and use
|
|
a temporary password:
|
|
|
|
```sh
|
|
METROPOLIS_RCON_HOST=127.0.0.1 \
|
|
METROPOLIS_RCON_PORT=25575 \
|
|
METROPOLIS_RCON_PASSWORD=... \
|
|
METROPOLIS_SERVER_DIR=/path/to/server \
|
|
./gradlew integrationTest
|
|
```
|
|
|
|
Set `METROPOLIS_WORLD` if the test world is not named `world`. These tests do
|
|
not cover the broader in-game workflows in [human-tests.md](docs/human-tests.md).
|
|
|
|
## Operational Safety
|
|
|
|
Use the build/test commands above for ordinary contribution work. The scripts
|
|
under `tools/` also include server start/stop, deployment, backup/restore, and
|
|
publishing operations; they are not required for a normal build. Read a
|
|
script before use and get explicit authorization before running operational
|
|
or release actions. In particular, `stop-server.sh` matches Paper jar
|
|
processes by command line, and `restore-server.sh` replaces matching top-level
|
|
server items from an archive. Never commit `.env`, credentials, server state,
|
|
or generated build output.
|
|
|
|
## Optional References
|
|
|
|
- [README.md](README.md): player/server-admin usage reference.
|
|
- [human-tests.md](docs/human-tests.md): manual pre-release checklist, not an
|
|
automated test report.
|
|
- [TODO.md](docs/TODO.md): historical backlog; the maintained plan is
|
|
[modernization-plan.md](docs/modernization-plan.md).
|
|
- [Modrinth description](docs/modrinth-description.md): hosting copy reference.
|
|
- [Scraper metadata](docs/project-description.md) and
|
|
[schema](docs/projects.schema.json): consuming-site project entry.
|