Development workflow

Complete contribution flow

Fork and clone

Fork the repository on GitHub, then clone your fork locally:

git clone https://github.com/<your-username>/server.git
cd server
git remote add upstream https://github.com/LandSandBoat/server.git

Create a branch

Always work on a dedicated branch — never commit directly to base:

git checkout -b my-feature-branch

Branch names should be short and descriptive. Use hyphens as separators.

Ask questions early

Before investing significant time, ask in Discord or open a draft PR describing your approach. It is always better to ask than to rewrite a large implementation.

Write code and commit

Make small, focused commits with meaningful messages. See Commit messages below.

Set up the dev environment

Install dependencies and build locally, or use the Docker dev environment. See Dev environment setup.

Test your changes

Run the test suite before submitting. See Testing for details.

Open a pull request

Push your branch and open a PR against LandSandBoat/server:base. Fill in all template checkboxes. Open as a Draft if the work is still in progress.

Address review feedback

After a staff member leaves feedback, fix or address every comment. Once the template checkboxes are checked and review is clear, the PR will be merged.

Commit messages

Commit messages should be meaningful. Amend or rebase local commits before pushing if the history is noisy.

Citing sources

Always cite your sources. Put citations in code comments or commit messages — not only in PR descriptions, which get lost over time:

Fix Disengage timing for melee to match retail behavior

Retail packet capture reference: <link-or-description>
See also: https://bg-wiki.com/ffxi/Disengage

Crediting co-authors

If you are committing work done on someone else’s behalf, give them credit using git’s --author argument or GitHub’s Co-Authored-By trailer:

git commit --author="Original Author <author@example.com>" -m "Fix mob respawn timer"

git commit -m "Fix mob respawn timer

Co-Authored-By: Original Author <author@example.com>"

Dev environment setup

Prerequisites

CMake ≥ 3.25
A C++20 compiler: GCC 14, Clang 20, MSVC (VS 2025), or Apple Clang
Python 3 + pip
MariaDB (for database)
Git

Install Python dependencies

pip install -r tools/requirements.txt

Build with CMake

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel

Environment variables

Database credentials can be passed as environment variables, avoiding the need to edit settings files:

export XI_NETWORK_SQL_HOST=localhost
export XI_NETWORK_SQL_PORT=3306
export XI_NETWORK_SQL_DATABASE=xidb
export XI_NETWORK_SQL_LOGIN=xiadmin
export XI_NETWORK_SQL_PASSWORD=password

Local CI with Docker

The dev.docker-compose.yml file mirrors the CI environment and lets you run all checks locally without a local C++ toolchain.

Do not modify dev.docker-compose.yml directly. Copy it to docker-compose.yml and make your changes there.

Available services

Service	Description
`database`	MariaDB LTS instance
`build`	Compiles the project with GCC in Debug mode
`sanity_checks`	Runs shell-based sanity checks against `origin/base`
`lls`	Runs the Lua Language Server check
`clang_tidy`	Builds with Clang and runs clang-tidy, outputs `log/clang_tidy_summary.md`
`setup_database`	Runs `dbtool.py update` to populate the database
`test`	Runs `xi_test --keep-going`
`startup_checks`	Runs startup validation checks

Running individual services

# Build the project
docker compose -f dev.docker-compose.yml run --build build

# Run tests
docker compose -f dev.docker-compose.yml run --build test

# Run clang-tidy
docker compose -f dev.docker-compose.yml run --build clang_tidy

# Run Lua Language Server
docker compose -f dev.docker-compose.yml run --build lls

# Run sanity checks
docker compose -f dev.docker-compose.yml run --build sanity_checks

Set LOCAL_WORKSPACE_FOLDER to your repo root before running Docker Compose commands to ensure volume mounts are correct:

export LOCAL_WORKSPACE_FOLDER=$(pwd)

Contributing

Architecture

Tools

Complete contribution flow

Commit messages

Citing sources

Crediting co-authors

Dev environment setup

Prerequisites

Install Python dependencies

Build with CMake

Environment variables

Local CI with Docker

Available services

Running individual services

​Complete contribution flow

​Commit messages

​Citing sources

​Crediting co-authors

​Dev environment setup

​Prerequisites

​Install Python dependencies

​Build with CMake

​Environment variables

​Local CI with Docker

​Available services

​Running individual services

Complete contribution flow

Commit messages

Citing sources

Crediting co-authors

Dev environment setup

Prerequisites

Install Python dependencies

Build with CMake

Environment variables

Local CI with Docker

Available services

Running individual services