Skip to content

Commit 38f6d85

Browse files
remduiremdui
committed
Add docs
1 parent 50b90e8 commit 38f6d85

6 files changed

Lines changed: 314 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 60 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,61 @@
11
# ServerFeatures
2-
Commands and features on server level
2+
3+
One modular feature framework for your Paper server.
4+
5+
## Quick Start
6+
7+
1. Place `ServerFeatures.jar` in your Paper `plugins/` directory.
8+
2. Install optional dependencies required by the features you plan to run.
9+
3. Start the server once to generate runtime config files.
10+
4. Enable the features you want in `plugins/ServerFeatures/config.yml`.
11+
5. Use `/serverfeatures list` and `/serverfeatures info <feature>` to verify state.
12+
13+
## Requirements
14+
15+
- Java 21
16+
- Paper 1.21.x (`api-version: 1.21`)
17+
- Feature-dependent optional plugins:
18+
- `DataRegistry`
19+
- `DataProvider`
20+
- `packetevents`
21+
- `PlaceholderAPI`
22+
- other integrations (for example Vault, LuckPerms, WorldGuard) only when using related features
23+
24+
## Build From Source
25+
26+
Add GitHub Packages credentials for Maven server id `github` in `~/.m2/settings.xml`:
27+
28+
```xml
29+
<settings>
30+
<servers>
31+
<server>
32+
<id>github</id>
33+
<username>YOUR_GITHUB_USERNAME</username>
34+
<password>YOUR_TOKEN</password>
35+
</server>
36+
</servers>
37+
</settings>
38+
```
39+
40+
Use a token with `read:packages` (and `repo` if package source repositories are private), then run:
41+
42+
```bash
43+
mvn -B package
44+
```
45+
46+
Output jar: `target/ServerFeatures.jar`
47+
48+
## Learn More
49+
50+
- [Configuration Guide](docs/CONFIGURATION.md)
51+
- [Documentation Index](docs/README.md)
52+
- [Architecture](docs/ARCHITECTURE.md)
53+
- [Development Notes](docs/DEVELOPMENT.md)
54+
- [Testing and Quality](docs/TESTING.md)
55+
- [Contributing](CONTRIBUTING.md)
56+
57+
## Community
58+
59+
- [Support](SUPPORT.md)
60+
- [Security Policy](SECURITY.md)
61+
- [Code of Conduct](CODE_OF_CONDUCT.md)

‎docs/ARCHITECTURE.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Architecture Overview
2+
3+
ServerFeatures is built as a modular system for Paper. Functionality is split into independent feature modules that can be enabled, disabled, and reloaded through configuration and commands.
4+
5+
## Design Goals
6+
7+
- Keep feature implementations isolated to reduce cross-feature regression risk.
8+
- Centralize lifecycle concerns (listeners, tasks, commands, caches, data access).
9+
- Let operators roll out features incrementally instead of all at once.
10+
11+
## Runtime Model
12+
13+
At startup, the plugin:
14+
15+
1. Initializes shared config and localization handlers.
16+
2. Discovers available feature classes through package scanning.
17+
3. Resolves metadata and dependency requirements.
18+
4. Prunes features with unresolved dependencies.
19+
5. Loads enabled features in dependency-safe order.
20+
21+
During runtime, each feature extends `BukkitBaseFeature` and uses `FeatureLifecycleManager` services for:
22+
23+
- listener registration
24+
- scheduled tasks
25+
- command registration
26+
- optional data access (`DataProvider`)
27+
- cache and GUI lifecycle
28+
29+
On disable/reload, feature cleanup cancels tasks, unregisters listeners/commands, closes data connections, and clears cache/GUI state to avoid leaks.
30+
31+
## Configuration and Data
32+
33+
- `config.yml` is the primary control surface (`features.*` + global keys).
34+
- Feature defaults are injected and unknown keys can be reconciled/cleaned per schema.
35+
- Feature-local config files live in `local/*.yml`.
36+
- Localization files live in `lang/*.yml`.
37+
38+
## Why This Matters
39+
40+
For operators, this architecture means safer rollout and easier troubleshooting.
41+
42+
For contributors, it means clear ownership boundaries: keep feature logic inside the feature, and keep shared behavior in the framework.

‎docs/CONFIGURATION.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Configuration Guide
2+
3+
This guide focuses on practical setup and safe operations. Keep changes small, test often, and roll out in steps.
4+
5+
## Configuration Layout
6+
7+
- Main settings: `plugins/ServerFeatures/config.yml`
8+
- Feature-local files: `plugins/ServerFeatures/local/*.yml`
9+
- Localization files: `plugins/ServerFeatures/lang/*.yml`
10+
11+
`config.yml` is generated at runtime and primarily controls feature enablement and feature-level settings.
12+
13+
Most features follow the same pattern:
14+
15+
- `enabled` toggle
16+
- feature-specific settings under that feature section
17+
18+
## Runtime Control Commands
19+
20+
Use these commands during operations:
21+
22+
- `/serverfeatures list`
23+
- `/serverfeatures info <feature>`
24+
- `/serverfeatures enable <feature>`
25+
- `/serverfeatures disable <feature>`
26+
- `/serverfeatures reload <feature>`
27+
- `/serverfeatures softreload <feature>`
28+
- `/serverfeatures reloadlocal`
29+
30+
## Recommended Workflow
31+
32+
1. Enable only the features you currently need.
33+
2. Roll out one feature (or one related group) at a time.
34+
3. Validate logs and in-game behavior.
35+
4. Move to the next feature only after verification.
36+
37+
This keeps incidents small and rollback simple.
38+
39+
## Environment-Specific Values
40+
41+
Treat production tokens, webhooks, and credentials as environment-specific values:
42+
43+
- keep secrets out of committed files;
44+
- use your secret-management workflow;
45+
- document expected variables for your team.
46+
47+
## Localization
48+
49+
You can override messages without copying all language keys.
50+
51+
Use partial language files with only the entries you want to customize. Missing keys fall back to defaults.
52+
53+
## Troubleshooting Tips
54+
55+
- If a feature does not enable, verify plugin dependencies and feature dependencies first.
56+
- If a setting seems ignored, check path names and indentation.
57+
- Apply one change at a time when diagnosing configuration behavior.

‎docs/DEVELOPMENT.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Development Notes
2+
3+
This page is for contributors who want a fast, reliable local workflow.
4+
5+
## Local Setup
6+
7+
```bash
8+
mvn -q -DskipTests compile
9+
```
10+
11+
Useful commands during development:
12+
13+
```bash
14+
mvn -q test
15+
mvn -B verify
16+
mvn -B -DskipTests checkstyle:check
17+
mvn -B package
18+
```
19+
20+
## Recommended Workflow
21+
22+
1. Create a branch for one focused change.
23+
2. Implement behavior and tests in the same pass.
24+
3. Run local validation (`test` at minimum).
25+
4. Update docs when behavior or operator workflow changes.
26+
5. Open a PR with context, impact, and migration notes when relevant.
27+
28+
## Engineering Guidelines
29+
30+
- Keep feature boundaries clean; avoid unnecessary cross-feature coupling.
31+
- Prefer typed config access (`ConfigView` / `ConfigNode`) over raw casts.
32+
- Make external calls fail-safe and time-bounded.
33+
- Ensure disable/reload paths release resources cleanly.
34+
- Keep logic testable; avoid burying behavior in hard-to-reach static paths.
35+
36+
## Feature Authoring Checklist
37+
38+
When adding a new feature module:
39+
40+
1. Implement metadata in `features/<feature>/meta/Meta`.
41+
2. Extend `BukkitBaseFeature` and define `getDefaultConfig()` / `getDefaultMessages()`.
42+
3. Register listeners/tasks/commands through lifecycle managers.
43+
4. Add feature tests under the mirrored `src/test/java/...` package path.
44+
5. Validate enable/disable/reload behavior with no leaked resources.
45+
46+
## Before You Open a PR
47+
48+
- Build succeeds locally.
49+
- Relevant tests pass.
50+
- New behavior is covered by tests.
51+
- Operationally important failures are logged clearly.

‎docs/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# ServerFeatures Docs
2+
3+
This folder is the practical guide for running, maintaining, and contributing to ServerFeatures.
4+
5+
## Start Here
6+
7+
If you run the plugin:
8+
9+
- [Configuration](CONFIGURATION.md): day-to-day setup and safe change workflow.
10+
- [Architecture](ARCHITECTURE.md): how feature discovery, dependency resolution, and lifecycle cleanup work.
11+
12+
If you contribute code:
13+
14+
- [Development](DEVELOPMENT.md): local setup and coding workflow.
15+
- [Testing](TESTING.md): test strategy and local validation commands.
16+
- [Contributing Guide](../CONTRIBUTING.md): pull request expectations.
17+
18+
## Release Notes
19+
20+
Releases are tag-driven (`v*` tags trigger packaging and publication).
21+
22+
Typical flow:
23+
24+
1. Ensure CI is green on your target branch.
25+
2. Bump version and create a release tag.
26+
3. Push branch and tag, then monitor the release workflow.

‎docs/TESTING.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Testing and Quality
2+
3+
Testing in this project is designed to catch regressions early while keeping contributor workflow practical.
4+
5+
## Test Structure
6+
7+
Tests are organized under `src/test/java` and mirror production package boundaries:
8+
9+
- API tests for public contracts and utility behavior
10+
- framework tests for lifecycle, config, command, and loader logic
11+
- feature tests for feature-specific logic and edge cases
12+
13+
Shared helpers live under `src/test/java/nl/hauntedmc/serverfeatures/util`.
14+
15+
## Local Commands
16+
17+
Run tests:
18+
19+
```bash
20+
mvn -q test
21+
```
22+
23+
Run the full quality gate:
24+
25+
```bash
26+
mvn -B verify
27+
```
28+
29+
Run lint checks:
30+
31+
```bash
32+
mvn -B -DskipTests checkstyle:check
33+
```
34+
35+
Generate a local coverage report:
36+
37+
```bash
38+
mvn -q test jacoco:report
39+
```
40+
41+
## What to Test
42+
43+
When you change behavior, add or update tests near that behavior:
44+
45+
- feature changes: user-visible logic, edge cases, fallback behavior
46+
- framework changes: lifecycle and dependency-resolution contracts
47+
- API changes: conversion, fallback, error handling, and stability guarantees
48+
49+
Focus on regression-prone logic paths (branching rules, validation, parsing, state transitions).
50+
51+
## Test Quality Bar
52+
53+
Use these rules during authoring and review:
54+
55+
- prefer behavior assertions over "does not throw" smoke checks;
56+
- avoid tests that only mirror declaration state (pure enum/constant checks);
57+
- avoid pure getter/setter round-trip tests unless they protect a real invariant;
58+
- assert observable outcomes for both happy and failure paths.
59+
60+
## Coverage Workflow
61+
62+
Use this when doing a full feature/class/method scan:
63+
64+
1. Run `mvn -q test jacoco:report`.
65+
2. Review `target/site/jacoco/index.html` and sort by missed lines/branches.
66+
3. Use `target/site/jacoco/jacoco.csv` to find high-risk classes with high missed lines and branches.
67+
4. Add tests for behavior-heavy methods first.
68+
69+
Prioritize methods with both high line miss and high branch count.
70+
71+
## CI
72+
73+
CI runs:
74+
75+
- Checkstyle (`ci-lint.yml`)
76+
- Tests and coverage (`ci-tests-and-coverage.yml`)
77+
78+
Tag pushes (`v*`) trigger release packaging and publication (`release-package.yml`).

0 commit comments

Comments
 (0)