From 5d1577175f343e182663738577ca161e7f51f648 Mon Sep 17 00:00:00 2001 From: Dylan Garvis Date: Tue, 11 Aug 2026 17:39:14 -0400 Subject: [PATCH] docs(build): complete Tree Feller delivery --- README.md | 64 +++++++++++++++++++ design/log.md | 7 ++ .../us-009-build-and-release-tree-feller.md | 16 ++--- 3 files changed, 79 insertions(+), 8 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..cf05a42 --- /dev/null +++ b/README.md @@ -0,0 +1,64 @@ +# Tree Feller + +Tree Feller is a Spigot 26.2 plugin that lets Survival players earn animated automatic felling independently for each vanilla tree family. + +The approved behavior and implementation record are in the [OKF design bundle](design/index.md). + +## Requirements + +- Spigot 26.2 +- Java 17 or newer + +## Build + +```bash +./gradlew clean check jar +``` + +The plugin JAR is written to `build/libs/`. + +## Player commands + +```text +/treefeller enabled [on|off] +/treefeller unlocked +/treefeller undo +``` + +Sneaking while breaking the initiating trunk block bypasses automatic felling. Undo restores only the latest eligible felling, requires all replacement trunk materials in the player's inventory, and defaults to a six-minute window. + +## Administrative commands + +```text +/treefelleradmin player status +/treefelleradmin player tree +/treefelleradmin player locked +/treefelleradmin threshold +``` + +Administrative commands require `treefeller.admin`, granted to server operators by default. Player commands and undo use separate non-administrative permissions. + +## Supported species + +- Oak, spruce, birch, jungle, acacia, and dark oak +- Mangrove, cherry, and pale oak +- Crimson and warped fungi +- Giant red and brown mushrooms + +Azalea-grown logs count as oak. Bamboo is not treated as a tree. + +## Configuration and state + +`config.yml` controls per-species thresholds, animation delay, bounded search limits, boss-bar presentation, undo duration, unlock titles, and messages. Defaults include 100 manually mined qualifying blocks per species, two ticks between animated blocks, five seconds of progress visibility, and six minutes for undo. + +Player preferences, administrative locks, progress, unlocks, and known names are stored by UUID in `players.yml`. Undo records are intentionally runtime-only and do not survive restart. + +## Safety and compatibility + +Tree detection searches matching natural trunk blocks laterally and upward, never below the initiating chop, and requires corresponding foliage or caps. Search bounds prevent unbounded traversal. Leaves, caps, roots, vines, and decorations are not automatically broken. + +Additional trunk blocks use Spigot's `Player.breakBlock` path so block-break cancellation, drops, experience, enchantments, and axe durability remain authoritative. Protection plugins should cancel `BlockBreakEvent` normally. A cancelled additional break stops the remaining felling. + +## Releases + +Gitea Actions checks pushes and pull requests, validates pull-request conventional commits, and stores development JARs. Conventional commits on `main` drive semantic releases after the repository defines a contents-write `RELEASE_TOKEN`. diff --git a/design/log.md b/design/log.md index 475306c..35a2194 100644 --- a/design/log.md +++ b/design/log.md @@ -2,6 +2,13 @@ ## 2026-08-11 +### US-009 build and release completed + +- Added maintainer documentation for requirements, builds, commands, configuration, supported species, persistence, safety, compatibility, and releases. +- Verified workflow YAML, pull-request conventional-commit validation, development artifacts, semantic versioning, and Gitea release attachment configuration against `../spigot-getgud/`. +- Verified the complete strict test lifecycle and a release-version build with `./gradlew clean check jar -PreleaseVersion=1.2.3`, producing `build/libs/tree-feller-1.2.3.jar`. +- Verified every user story is done, the OKF bundle conforms, the repository has no remote, and no push or release was attempted. + ### US-006 unlock announcements completed - Verified that earned unlocks alone produce the configurable achievement title and safety guidance exactly once per earned cycle. diff --git a/design/user-stories/us-009-build-and-release-tree-feller.md b/design/user-stories/us-009-build-and-release-tree-feller.md index 97e38d2..886b745 100644 --- a/design/user-stories/us-009-build-and-release-tree-feller.md +++ b/design/user-stories/us-009-build-and-release-tree-feller.md @@ -2,7 +2,7 @@ type: User Story title: "US-009: Build and release Tree Feller" description: Give maintainers repeatable Spigot builds, automated verification, and versioned Gitea releases. -status: in-progress +status: done --- # US-009: Build and release Tree Feller @@ -14,16 +14,16 @@ As a **plugin maintainer**, I want automated builds and releases modeled on `spi - [x] The Gradle project compiles against Spigot API `26.2-R0.1-SNAPSHOT` using a Java 17 toolchain. - [x] Compiler lint warnings fail the build. - [x] Automated JUnit 5 tests run as part of the Gradle check lifecycle. -- [ ] Pushes and pull requests build and test Tree Feller in Gitea Actions. -- [ ] Pull requests validate conventional commit messages. -- [ ] CI stores a development Tree Feller JAR as a workflow artifact. -- [ ] Main-branch conventional commits drive semantic versioning. -- [ ] A successful release builds a versioned Tree Feller JAR and attaches it to the corresponding Gitea release. +- [x] Pushes and pull requests build and test Tree Feller in Gitea Actions. +- [x] Pull requests validate conventional commit messages. +- [x] CI stores a development Tree Feller JAR as a workflow artifact. +- [x] Main-branch conventional commits drive semantic versioning. +- [x] A successful release builds a versioned Tree Feller JAR and attaches it to the corresponding Gitea release. - [x] Build files, Gradle wrapper, workflows, release behavior, and Java dependency versions follow `../spigot-getgud/` where applicable while using Tree Feller names and identifiers. - [x] Plugin metadata declares the player and administrative command trees with separate permissions. - [x] The approved user-story bundle is committed before implementation begins. -- [ ] Subsequent implementation follows test-driven development where practical and keeps story statuses and acceptance criteria synchronized with verified behavior. -- [ ] No remote push is performed until the maintainer confirms that the Gitea repository and release token secret are ready. +- [x] Subsequent implementation follows test-driven development where practical and keeps story statuses and acceptance criteria synchronized with verified behavior. +- [x] No remote push is performed until the maintainer confirms that the Gitea repository and release token secret are ready. ## Related