Contributing

The repositories

Everything lives in the LonelyIceProject organization on GitHub. Every repository works on the branch main.

Where a change goes

Rules for every repository

• License: GPL-2.0-or-later for the project's own repositories and plugins (the GPL v2 LICENSE, and "license": "GPL-2.0-or-later" in plugin.json). A wrapper carries the license of the module it builds, for example AGPL-3.0 for mod-transmog-plugin (Licenses).
• English for code, comments, commit messages and documentation. The launcher's interface text lives in src/assets/lang/<code>/*.lang and is read with Tr("key"); code carries no interface text.
• Commit messages follow conventional commits, type: subject or type(Scope): subject, with the types feat, fix, refactor, docs, chore (see each repository's history).

The core fork

The fork stays generic and upstreamable. Its README says so: changes that make sense for AzerothCore itself are written to be proposed upstream.

• No LonelyIce markers. Nothing in the fork names LonelyIce: no LONELYICE_* options, no launcher paths, no LonelyIce defaults. The launcher sets the fork's own options (AC_PLUGIN_ABI, WITH_PLAYERBOTS_HOOKS, ...) from outside.
• AzerothCore conventions. Commit messages as in .git_commit_template.txt, type(Scope/Subscope): subject (feat(Core/Plugins): ..., fix(CMake): ..., refactor(Core/Database): ...). New files start with AzerothCore's GPL header (This file is part of the AzerothCore Project. See AUTHORS file for Copyright information). Formatting follows .editorconfig (4 spaces, lines up to 120 characters).
• Only plumbing and exposure. What the plugin mechanism and the server start need, and generic extension points for plugins. Game changes belong in plugins.
• Backend-neutral. Anything MySQL-specific lives in the MySQL plugin. SQL in the core is written in AzerothCore's MySQL dialect and must translate for SQLite (SQL rules); check it with sqlconv.
• Plain programs keep working. worldserver, authserver and dbimport must build and run without the launcher, with shared libraries and without.

The same holds for the mod-playerbots fork: generic hooks (its ExternalHooks.h), the plugin build, and backend-neutral database access, while bot features built on top of it live in plugins such as mod-lonelyice-tactics.

Plugins

• They must work in a plain worldserver of the fork. The loader, configs and SQL are the core's; the launcher only adds settings, client patches and package handling on top (Plugin format).
• They never see the database backend. SQL files in AzerothCore's MySQL dialect, no backend-specific files or overrides/ folders (the one exception is a database the plugin owns and updates itself, as playerbots does); code through WorldDatabase, CharacterDatabase, LoginDatabase, prepared statements, transactions and ModuleDatabasePool only, never a driver (Shipping SQL).
• Ids. Your own plugins use author.feature; the project's plugins use lonelyice.*. On the site, the first upload of an id claims it. DBC rows get named ids from a patch recipe instead of fixed numbers (Client patches).
• Versions. Bump version in plugin.json with every change you release; the catalog and the package manager compare it.
• Languages. List in locales only the languages the player-facing texts are really translated into (locales).

Core changes and the ABI

A plugin library only works with the core build it was compiled against. When a core change can break existing plugin binaries (a changed class layout, a changed signature in a header), the ABI name moves on (ABI), as it did from lonelyice-ac-1 to lonelyice-ac-2. That move changed, together:

• AC_PLUGIN_ABI in the lonelyice top-level CMakeLists.txt, with the new external/azerothcore commit;
• core.abi in the plugin.json of every plugin, with a new version (chore: build for core ABI lonelyice-ac-2), and the plugin submodules in lonelyice.

The name also appears in supported_abis of the site's content/site.json (the ABIs the catalog accepts), in the documentation and guides, and in plugin READMEs.

Reporting bugs

Report on the forum (linked in the site's header) or in the GitHub issues of the repository concerned; when you do not know which one, use the issues of lonelyice, which the Support page links. Include what you did, what you expected, what happened, and the log from the server folder (Logs).

Submitting changes

1. Fork the repository on GitHub and create a branch from main.
2. Make the change following the rules above. For the core and plugins, build and run it: a plugin in LonelyIce and, where it matters, in a plain worldserver; SQL on SQLite and, when you can, on MySQL.
3. Update the documentation the change affects in the same pull request.
4. Open a pull request against main and describe what changed and how you tested it.

A change that spans repositories (a new extension point in the fork and a plugin that uses it) is a pull request in each; the fork's comes first, since the others build on it. lonelyice then moves its submodule pointers.

Packages go to the catalog through the site, not through pull requests: Publishing a package.

Documentation

The site does not edit the reference pages; tools/sync-docs.ps1 in lonelyice-website copies docs/*.md of a lonelyice checkout (by default the folder next to the website repository) into content/docs:

tools\sync-docs.ps1 -Launcher C:\dev\lonelyice

A new page also needs an entry in content/docs/nav.json; pages missing there appear under "More". Guides carry a header with title, category, level, summary and order.

The plugin loader is described twice, in the fork's doc/Plugins.md and in Plugin API; a change to the loader updates both. Link between pages with /docs/<name> and /guides/<name> instead of repeating their content.