From 5c7ef3a40226f1f5df528386ee1c365cef742ac3 Mon Sep 17 00:00:00 2001 From: Sam Sung <51686767+samwhosung@users.noreply.github.com> Date: Sat, 26 Sep 2026 15:56:47 +0700 Subject: [PATCH] contributing: where to start, a pull request finished here, and the counts and paths as they are (#433) Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/pull_request_template.md | 2 ++ README.md | 6 +++--- docs/CONTRIBUTING.md | 37 +++++++++++++++++++------------- docs/METHOD.md | 6 +++--- 4 files changed, 30 insertions(+), 21 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3a23b396..368962f6 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,5 +1,7 @@ +**The issue it fixes** (`Fixes #N`, if there is one) + **What this changes** **What 1.12.1 does, and how you know** (the client's behaviour, a DBC field, a FrameXML line, a capture) diff --git a/README.md b/README.md index d0d295c1..661e2898 100644 --- a/README.md +++ b/README.md @@ -84,9 +84,9 @@ player build to the tests. ## Contributing -Issues and pull requests are open. [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) says what gets -in and how a change is judged. Bugs, questions and ideas are welcome on the -[Discord](https://discord.gg/wJSJx467G4) too. +Issues and pull requests are open. [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) says where to +start, what gets in, how a change is judged and what happens to a pull request once it is open. +Bugs, questions and ideas are welcome on the [Discord](https://discord.gg/wJSJx467G4) too. --- diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 34126d0d..7dc3c497 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -5,6 +5,13 @@ creative: a change is accepted when it makes benilla more like 1.12.1 or fixes a evidence from the reference, in one small piece, with the gates green. Everything else is a fork, and forks are welcome. +## Where to start + +The [issues](https://github.com/samwhosung/benilla/issues) the maintainers file are checked +against 1.12.1 first: each says what 1.12.1 does, what benilla does instead, and where in the +code, and any of them is a place to start. Before you start one, look for an open pull request +that already covers it, and say `Fixes #N` in yours. + ## What gets in - A fix for a bug, with how to see it before and after. @@ -37,12 +44,12 @@ fork, and forks are welcome. ## After you open it -A maintainer reads it, checks it against the reference and runs it. Most pull requests are -finished here rather than sent back: a rebase onto main, a fix, a test or a comment, pushed to -your branch as commits on top of yours, so leave "Allow edits by maintainers" ticked. It lands as -one squash-merged commit with you as its author. When what would land is mostly ours, we land our -own version with you as a co-author and close yours with a note. One that is out of scope is -closed with the reason. +A maintainer reads it, checks it against the reference, runs it and finishes it here: a rebase +onto main, a fix, a test or a comment, added as commits on top of yours on your branch, so leave +"Allow edits by maintainers" ticked. It lands as one squash-merged commit with you as its author. +When what would land is mostly ours, we land our own version with you as a co-author and close +yours with a note, and when main already has the fix, we close yours and say where. One that is +out of scope is closed with the reason. ## Setting up @@ -54,12 +61,12 @@ closed with the reason. root, which only a dev build sees: the player build looks for `Data/` or `WoW/Data/` beside the binary. benilla reads the install and never writes into it. `WOW_DATA=` (set, empty) means "no install", which is how the no-install boot is tested on a machine that has one. -- **Without the install, green is hollow.** About a thousand tests read the install and skip - when it is absent; six more read a corpus of vanilla addons (`BENILLA_ADDON_CORPUS=`, or a `wow-addons-vanilla` link at the root), third-party content that is not in - this repo. `scripts/gates.sh` and `scripts/check.sh` print how many tests skipped and why. - Where the data is, `BENILLA_REQUIRE_DATA=1` turns a skip into a failure, and the gates set it - themselves when the install and the corpus both resolve. +- **Without the install, green is hollow.** Well over a thousand tests read the install and skip + when it is absent, and a few dozen more read a corpus of vanilla addons + (`BENILLA_ADDON_CORPUS=`, or a `wow-addons-vanilla` link at the root), + third-party content that is not in this repo. `scripts/gates.sh` and `scripts/check.sh` print + how many tests skipped and why. Where the data is, `BENILLA_REQUIRE_DATA=1` turns a skip into a + failure, and the gates set it themselves when the install and the corpus both resolve. - **A server to test against.** Any 1.12.1 server; `WOW_HOST` names it (default `localhost:3724`). A scripted run has no default account: `WOW_USER`, `WOW_PASS` and `WOW_CHAR` name a test account on your server whose login kicks nobody, all three, either in @@ -88,8 +95,8 @@ closed with the reason. ## Reporting a bug -Open an issue: what you did, what you saw and what 1.12.1 does instead, with the server and the -platform you ran on. Questions and ideas are welcome there or on the Discord linked from the -README. +Open an issue: what you did, what you saw and what 1.12.1 does instead, with the `benilla build` +line from the start of the terminal output, your platform and the server you ran on. Questions +and ideas are welcome there or on the Discord linked from the README. Working with an AI agent is expected. The agent reads `AGENTS.md`, and the same rules bind it. diff --git a/docs/METHOD.md b/docs/METHOD.md index fe8cd76c..5019bc2e 100644 --- a/docs/METHOD.md +++ b/docs/METHOD.md @@ -41,9 +41,9 @@ comment naming the reference fact and why we differ. Anything else is a fork. counterparts under `assets/ui` stay until they retire. - **The install is read-only.** benilla never writes into the WoW folder: no screenshot, log, cache or scratch file. `scripts/smoke.sh` fails a run that leaves the install changed. -- **Local state lives in one folder**, `benilla-config/` beside the binary, and every path to - it resolves through `crate::local_state`. Player settings are CVars persisted as a diff in - `benilla-config/config.toml`. +- **Local state lives in one folder**, `benilla-config/`, at the repo root in a dev build and + beside the binary in the player build; every path to it resolves through `crate::local_state`. + Player settings are CVars persisted as a diff in `benilla-config/config.toml`. - **UI is stock-first: a window is migrated, not authored.** The end state is the stock 1.12 FrameXML executed off the player's own chain. `assets/ui` does not grow: a test names its files and fails on a new one. A window is built by pointing `benilla.toc` at the stock file,