Skip to main content

​
Complete contribution flow

1

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
2

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.
3

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.
4

Write code and commit

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

Set up the dev environment

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

Test your changes

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

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.
8

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 <[email protected]>" -m "Fix mob respawn timer"

​
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

ServiceDescription
databaseMariaDB LTS instance
buildCompiles the project with GCC in Debug mode
sanity_checksRuns shell-based sanity checks against origin/base
llsRuns the Lua Language Server check
clang_tidyBuilds with Clang and runs clang-tidy, outputs log/clang_tidy_summary.md
setup_databaseRuns dbtool.py update to populate the database
testRuns xi_test --keep-going
startup_checksRuns 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)

Build docs developers (and LLMs) love

Get started for freeTalk to us