maj/Metropolis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updates documentation.

Browse Source
This commit is contained in:
Tom Hicks
2026-10-22 17:33:45 -07:00
parent 37f5e19fbd
commit 5de22ec0ea
12 changed files with 348 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
CONTRIBUTING.md
View File

@@ -1,18 +1,57 @@
# Contributing
# Contributing to Metropolis
## Development Setup
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.
Use Java 25 or newer. The Gradle wrapper downloads Gradle 9.8; dependencies are declared in `build.gradle` and resolved from Maven Central, PaperMC, and EngineHub.
## First Contribution
```sh
./gradlew build
```
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.
The standard build runs JUnit 5 tests without starting Minecraft. Tests use Mockito for Bukkit and external-plugin boundaries. Keep domain and configuration behavior testable without a running server.
## Architecture and Source Map
## Live Server Tests
- `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`.
Live tests are opt-in and run separately from `build`:
## 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 \
@@ -22,12 +61,27 @@ METROPOLIS_SERVER_DIR=/path/to/server \
./gradlew integrationTest
```
Use a disposable or backed-up Paper server with compatible WorldGuard and WorldEdit plugin jars installed. Keep RCON local, use a temporary password, and restore the server after tests that modify regions or worlds.
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).
## Pull Requests
## Operational Safety
- Keep changes focused and include tests for behavior changes.
- Run `./gradlew build` before submitting.
- Run `integrationTest` only when changing behavior that requires Paper or the external plugins; do not add it to the default build.
- Update `README.md` and project descriptions when user-facing setup, commands, or dependencies change.
- Keep generated build output, server data, credentials, and local `.env` files out of commits.
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.