Contributing

Polestar is a guide addon for WoW: Forever: a Lua 5.1 addon in addon/, the guides in guides/, and Node tools in tools/ that check, compile, play and package them. You can help without touching any code.

Ways to help#

A good wrong-step report#

The in-game report (the bug in the guide window) fills in most of this for you: the guide, the step and its goals, your position, your race, class and level, the versions and any errors Polestar caught. Add what is wrong.

• The guide and the step as the guide window shows them (the guide's title and the step's number and text).
• What is wrong: what the step says, and what you found in the game.
• The right spot: stand there and type /polestar where. It prints your map and position as guide lines (zone map <id> and goto <x>,<y> live) and opens them in a box you can copy from.
• Your race, class and level.
• Your Polestar version (shown at the foot of the Options sidebar and in the game's AddOns list).

How a report is handled#

A report is a lead, not a verdict: players are sometimes on an old version, have an incomplete install, misread a step or meet another addon's lines. Each report goes through the same steps before anything changes:

1. Check the version and install. The report's first line names the Polestar version. Is the step still the same on the coming release?
2. Reproduce it. In the data (data/forever/*.json, the compiled guide), in the test client (tests/, see tests/README.md) or in the game. A report that can't be reproduced gets an answer saying so, and why.
3. Check it against the sources. The game's own data, the web database's Forever database, recordings. A player's memory of Classic is not a source: Forever changed many quests.
4. Fix it only if it is real, with a test that fails before the fix and passes after it (or, for a guide, lint and playtest).
5. Credit the reporter in the fix's changelog entry, "(thanks <name>)", and tell them which release carries the fix.

Before you start#

Many people, and their agents, work on the same reports at once. These steps keep two of you from fixing the same thing without knowing:

1. Look for work already open. An issue with the label has-pr has a comment, "Pull requests for this issue", listing who is on it. Not every pull request names its issue, so search too: gh pr list --state open --search "<issue number>", then the quest id and the guide's name. When an open pull request covers it, help there instead of opening another: review it, try it in the game, or offer the part it is missing.
2. Start from a checked report. Issues labelled confirmed or patch-candidate have the evidence on them. Any other report is a lead: check it first (How a report is handled).
3. Say you are on it. Leave a short comment on the issue, and open your pull request early, as a draft while it is unfinished. Link the issue so it shows: the issue's number in the title ((#302)), or "closes #302" in the description, once for each issue it fixes. A plain mention ("see #302") is a link, not a claim, and does not list your pull request on the issue.
4. If your pull request gets the label overlap, another open pull request addresses the same issue (its comment names it). Compare the two and say on both what each covers. One is merged: the correct and complete one first, then the earlier. Useful parts of the other are carried over with credit to its author.
5. One issue, one pull request. The same bug in several guides is one pull request that fixes the pattern and lists every issue it closes.
6. A claim that went quiet (no commit or reply for a week) is free: say on the issue that you are taking it over, and go ahead.

An issue filed from the Discord #bugs forum tells its reporter in their thread when the first pull request for it opens, so link only what you are really fixing.

Fixing a guide#

Each guide's title leads to its file: the leveling guides live under guides/forever/<faction>/... (for example guides/forever/alliance/02-westfall.guide is "Westfall"), and the first line of every file names the guide's id. To find the step for a quest, search for the quest id:

git grep "accept 184"

• The format is in docs/GUIDE_FORMAT.md, and on one page in docs/GUIDE_CHEATSHEET.md.

• The comments at the top of a leveling guide explain the route's choices (where it comes from, the flow through the zone, what it leaves out). Read them before moving steps around, and update them when a fix changes the route: a later route refresh keeps every fix they document (see docs/SIMULATION.md, "Refresh").

• A fix for a player's report gets a case in tests/guides-reported.test.js (or tests/guides-caves.test.js for a cave mouth) that checks what the player sees, the goal order or where the arrow leads, not the guide's wording, so a refresh that undoes it fails the suite. A quest item that vanishes after a while is checked by lint itself (item ... lasts ...).

• When the guide is wrong because the data is (a giver, a spawn, a drop), fix the data in tools/lib/data/corrections.json too, so the simulator and the next route refresh see it.

• Do not commit addon/Polestar_Guides/Guides.lua.It is compiled from guides/ and data/forever; the maintainer runs node tools/polestar.js compile (via polestar regen) after merge. Never hand-edit it or splice in a hunk from a partial compile: a spliced hunk can still be valid Lua while the game never sees the goals it contains.

• Check your change:

  node tools/polestar.js lint                        # every compile check, writes nothing
  node tools/polestar.js playtest --filter westfall  # play the matching guides to the end for every class
  node --test tests/guides-reported.test.js          # or tests/guides-caves.test.js for a cave mouth

  --filter plays only the guides whose file or id contains its text; --class Warrior narrows it to one class. You don't need the full test suite; CI runs it on your pull request.

Both need the reference data (below). If you cannot build it, send the fix anyway: describe what you changed and why, say that you could not run the checks, and they are run before it is merged.

Setup#

• Node 24 or newer: every command.
• Lua 5.1 or LuaJIT: play, playtest, record import, travel route and the addon tests. $LUA picks one when you have several.
• The reference data, data/forever/: quest titles, givers and coordinates, used by every guide command. node tools/polestar.js data build assembles it from the Era quest database, Blizzard client tables and recordings, and reads the community quest database's Forever store from addons installed with your game (--no-<quest-db> builds without it). node tools/polestar.js help data lists the options; docs/PACKS.md has the install commands per system.

node tools/polestar.js doctor checks Node, Lua, the reference data, the AddOns folder and pack.json. node tools/polestar.js help lists every command.

Checks#

Run only the checks for what you changed. CI runs the full suite on every pull request and tells you if anything else broke.

A few tests skip automatically when the reference data (data/forever) or Lua 5.1 is missing. tests/README.md describes the suite; docs/SUITE.md what is in and out of scope.

You do not commit addon/Polestar_Guides/Guides.lua, docs/preview/*.svg, the locale files in addon/Polestar*/, or addon/Polestar/Media/*.tga unless your change is to the generator itself (a texture generator in tools/media/, the preview renderer in tools/preview/, or the compiler in tools/lib/dsl/). The maintainer regenerates those after merging your PR.

Code changes#

• docs/ARCHITECTURE.md explains how the addon and the tools fit together; docs/README.md maps every document.
• Behaviour changes come with tests that show the behaviour. Run the tests for what you changed (see Checks above); CI runs the full suite on every PR and tells you if anything else broke.
• For UI changes, node tools/polestar.js preview renders the guide window, menu and options to docs/preview/*.svg. Run it to review your change visually; CI runs it on every PR to verify the renderer still works. docs/DESIGN.md describes the visual system. The renders use frozen sample guides, not the shipped ones, so a guide edit never changes them.
• Player-facing text is a literal L["..."]. Adding, changing or removing a string does not require any extra step from you: CI checks the existing locale files and the maintainer runs i18n sync after merge to propagate new strings to the locale files.

Branches#

Every pull request goes to next: guide fixes, the addon, the tools, the data builds, translations, new guides and route refreshes. Never to main or a hotfix/ branch; the Base branch check fails those.

A guide fix players need before the next feature release still starts on next. Once it merges, the maintainer adds the backport label, and a pull request picking it onto the open hotfix/ branch opens on its own. A patch carries only guide fixes: changes to guides/, the recompiled addon/Polestar_Guides/, the fix's test, tools/lib/data/corrections.json and its changelog fragment in changes/, and it has to work with the released addon. You don't need to do anything for this; if you think your fix belongs in the coming patch, say so in the pull request.

After a patch ships, main is merged into next, so next always has every released fix. docs/RELEASING.md has the release side.

Using an AI agent#

Agents are welcome. AGENTS.md (opens in a new tab), which most coding agents read on their own, sends them to the skill for their task in skills/: polestar-contributing for any change or pull request, polestar-triage for checking a report, polestar-guide-fix for fixing a guide step and polestar-guide-pack for writing a community addon. Your own agent settings and notes stay yours: keep them out of commits. Claude Code reads AGENTS.md only while you have no CLAUDE.md or CLAUDE.local.md of your own; if you write one, start it with @AGENTS.md. The rules that matter most:

• A bug report is a lead, not a verdict, from a player or from their agent. Check it against the guide, the data and Forever's own sources before changing anything; Classic knowledge is not a source (see How a report is handled).
• Never claim a check ran when it did not, and never invent quest ids, coordinates or names.
• You answer for what your agent opens, pushes or posts. Read its comments before they go up, and say in the pull request that an agent helped — tick the checkbox and fill in the exact model name and version and the app or CLI (for example "Claude Sonnet 4.6 via Claude Code", or "GPT-4o via Codex"). The maintainer uses that to decide how carefully to re-verify the work.

Installing the skills#

Install the skills to have them in your agent outside a clone too, for example to start on an issue. The --sparse paths fetch only the skills, not the whole repository:

Run npx skills with -g: without it, it writes the skills into the folder you are in. Start a new session after installing. An agent picks a skill when your request matches it; to be sure, name it: "use polestar-triage on #123".

Commits and pull requests#

• Base branch: see Branches.

• One change per commit.

• Plain messages that describe the change for the players or authors it affects (for example "Westfall: turn in at Sentinel Hill before the farms"), not how it was made.

• Behaviour changes come with tests that show the behaviour.

• Each change brings its changelog entry as a file of its own in changes/ (a fragment), not an edit to CHANGELOG.md: with many pull requests open at once, they would all edit the same lines. The release assembles them into CHANGELOG.md. Write it with

  node tools/polestar.js changelog add players --name westfall-sentinel-hill --text "Westfall turns in at Sentinel Hill before the farms (thanks Tom)."

  (players, authors or contributors: the "For players", "For guide authors" and "For contributors" headings), or by hand as in changes/README.md (opens in a new tab). changelog check (run in CI) checks every fragment and changelog show prints them as the release will. A fix for a reported bug (Discord, an issue, the in-game report) credits the person who reported it at the end of its entry, by the name they reported under: "(thanks Tom)". A contribution credits its author the same way.

• A guide fix that should also go out in the coming patch: say so in the pull request. The maintainer adds the backport label when it merges, and a pull request picking it onto the hotfix/ branch opens on its own (docs/RELEASING.md).

How a pull request is reviewed#

Every pull request is read for safety before any of its code is run: its tests run Node tools on the maintainer's machine and Lua in the test client, so running them is already trusting them. The diff is read in full, generated files included, and the pull request waits while anything below is unexplained.

Then the change is reviewed for correctness (tests, the game's limits, Options toggles off by default for anything that spends, equips or acts for the player) and merged into its base branch.

AI-assisted pull requests: the model named in the "Model and tool" line sets how carefully the work is re-verified. Pull requests from smaller or unnamed models have their claims, generated files and tests re-run before merge; pull requests that leave the line blank are treated the same way.

License#

Contributions to Polestar are under GPL-3.0 (LICENSE (opens in a new tab)). Community addons written by others are separate works; see LICENSE-EXCEPTION.md.