Everloot is built from what players see, so you can help without touching any code.
- Play with the addon and upload. Every upload adds to the data, and the site states a fact
once three installs have reported it, so your upload can be the one that confirms it. Install the addon from
everloot.app/addon, play, log out, upload your
SavedVariables/Everloot.lua. You preview everything before it is sent. - Upload your Polestar Recorder file. If you record with the
Polestar Recorder, upload
SavedVariables/Polestar_Recorder.luaon everloot.app/upload: its NPC positions, quests, dungeon entrances, bosses and treasures count toward the same three-install rule, and its loot windows are counted until they can join the drop rates. - Report wrong data. A drop that never drops, a vendor price that is off, a recipe colour that does not match your window: open an issue with the Wrong data form. Say what the page shows, what you saw in the game, and where (zone and coordinates if you have them).
- Report a bug. Use the Bug report form. For addon problems, paste the output of
/everloot status. - List your addon. An addon page at everloot.app/addons/ exists only for an addon the owner approved. Ask for one with the Addon listing request form.
- Offer a guide. Read
docs/GUIDES.md, then use the Guide submission form with your sources and a link to your draft. - Fix the lore archive. The lore pages come from the 2023 Warcraft Wiki dump. If the importer turns a page into nonsense (broken templates, missing text), an issue with the page link helps us fix the importer for every page like it.
- Write code. See below.
Questions and ideas go in Discussions.
New here? Open the issues labelled
good first issue. Each is small,
says what done looks like, and names the files to start in. Comment on one to say you are taking it,
and ask in Discussions if anything is unclear.
help wanted marks larger work that is
open to anyone, and documentation marks
docs fixes. For context on what is still open, read the long-form backlog in
docs/2026-10-28-platform-gap-register.md. The area labels
under Labels tell you which part an issue touches.
Read docs/DATA_POLICY.md before adding any data. In short: no scraping, no
reading the game client's memory or files beyond the addon's own save file, no spoilers. A new source goes in
docs/sources/LEDGER.md in the same pull request, and only sources
whose licence allows republishing under CC BY-SA 4.0 can reach a release.
You need Node 22, Python 3.12 and Git. Each part's README says how to run and test it:
addon/: Lua 5.1, tested throughlupaweb/: Next.js;npm run sample-releasegives you local lore pageskb/: the knowledge base and MCP servercompanion/: needswebinstalleddesktop/: Electron; needswebandcompanioninstalledpackages/protocol/: the contract. After a change there, runnpm run buildinpackages/protocol, then in each ofweb,kbandcompaniondeletenode_modules/@everloot/protocoland runnpm install: they install a packed copy, and npm keeps the old one while the version number is unchanged. Commit the regenerateddist/andschema/.
How the live site is run day to day is docs/OPERATIONS.md.
To catch lint and type errors before CI does, turn on the pre-push check once per clone:
git config core.hooksPath .githooks. It lints and typechecks only the packages your push changes.
Every commit needs a Signed-off-by: line. It certifies that you wrote the change, or have the right
to submit it, under the project's licence (Developer Certificate of Origin).
Add it with -s:
git commit -s -m "Fix the vendor price rounding"
If CI says a commit is not signed off, fix the last commit with git commit --amend -s --no-edit,
or several with git rebase --signoff main, then force-push your branch. Commits from GitHub's own
bots, such as Dependabot, are exempt: a bot cannot certify anything.
Title a pull request type(scope): plain sentence. The title becomes the line in the release notes,
so write it for someone reading them.
- Types:
feat,fix,perf,refactor,docs,chore,data - Scopes:
addon,web,kb,companion,desktop,protocol,mcp,game-data,infra,docs - Example:
feat(web): the raid builder shows which tree each buff needs
A check on every pull request rejects a title that does not fit. No full stop at the end, 100 characters at most.
- The tests for the parts you touched pass (see
.github/workflows/checks.ymlfor the exact commands CI runs). - An addon change to a version that is not released yet rebuilds the zip with
python scripts/package-addon.pyand commits it; CI fails if the zip does not match the source. Once the version is tagged, its zip stays as published: CI only checks that the source still packages, and the next release builds the new zip. - Data changes follow the data rules above.
- Add a line to
CHANGELOG.md(see Changelog). - Set the area label (see Labels). Maintainers use it to group the release notes.
- Keep a pull request to one change. Say what changed and how you tested it.
Add one line for your pull request under ## [Unreleased] in CHANGELOG.md, as the last bullet of
### Changed for a change to something that exists, ### Added for something new, or ### Fixed for a fix.
Start the line with the part it touches: - Site:, - Addon:, - Docs:, - Knowledge base:,
- Protocol:, - MCP:, - Companion: or - Desktop App:. Write it for a reader of the release notes. A change
with nothing a user would notice needs no line.
Unreleased means not yet in a tagged addon or desktop release. Site and MCP server lines are already live
once the pull request merges. Addon and desktop lines wait for the next tag. The release moves the
section under the version (step 3 of "Stable release" in docs/RELEASING.md).
Maintainers set labels. The descriptions are the ones in the repository's label list.
- Area:
addon(the in-game Lua addon),web(everloot.app),kb(the knowledge base and MCP server),mcp,companion,desktop,protocol,tools(talent calculator, raid builder, map),lore,game-data(read from the game files),ecosystem,infra,security,privacy,data. - State:
needs-triage(not looked at yet),needs-info(waiting for more detail from the reporter),confirmed(a maintainer reproduced it),cant-reproduce(closed: we could not reproduce it),known-issue(listed in the pinned Start here post in Discord #help),needs-decision(waiting for a maintainer decision),spoiler(touches unreleased content found in game files). - Automation:
from-discord(reported in the Discord #help or #ideas forum),site-down(everloot.app failed its health check),night-shift,dependencies(Dependabot updates). Anight-shiftissue is a small, self-contained fix that the overnight loop takes as one reviewed pull request. It is never merged without a maintainer.
CI also scans every pull request for leaked secrets and for private file paths.
docs/WORKFLOWS.md describes every workflow.
- The site deploys from
main: a merged pull request is live a few minutes later. - The addon gets a new version number in
addon/Everloot.tocandaddon/core.lua, a rebuilt zip inweb/public/downloads/, a tagged GitHub release and an upload to CurseForge by a maintainer. A nightly pre-release is built frommainwhen it has changed.docs/RELEASING.mdhas the steps. - The desktop app gets a new version in
desktop/package.json, adesktop-vX.Y.Zsection inCHANGELOG.mdand adesktop-vX.Y.Ztag; the release workflow builds the installers and publishes them withSHA256SUMS.desktop/README.mdhas the steps. - The knowledge release (the lore archive) is rebuilt by a maintainer from the wiki dump with
npm run kb -- snapshot, checked withnpm run kb -- audit-sources, and published to the site's storage. The site refuses a release that does not match its manifest.
By contributing you agree that your code is licensed under the AGPL-3.0-only and any data under CC BY-SA 4.0, like the rest of the project. Everyone here follows the code of conduct.