Welcome! This guide outlines the process for contributing code and improvements to Stockfish. Following these steps ensures your changes can be reviewed, tested, and integrated smoothly.

• Guiding Principles
• Getting Started: One-Time Setup
• The Contribution Workflow
  • Step 1: Sync Your Fork
  • Step 2: Create a New Branch and Make Changes
  • Step 3: Run Your Test on Fishtest
• Submitting Your Pull Request
• Reference: Testing Methodology
• Reference: Advanced Topics & Tools

• Be Respectful: Always interact politely and kindly. See the Open Source Etiquette Guidebook.
• Keep Changes Small: Submit focused, atomic changes. Small patches are easier to review and understand.
• One Idea Per Test: Each test should focus on a single idea. Avoid bundling multiple changes into one patch.
• Passing Tests ≠ Automatic Merge: Your change still needs to be reviewed by maintainers, even if it passes all tests. Complex changes require significant benefits to be considered.
• Join the Community: Participate in the Stockfish Discord server. It's the primary place to communicate with developers and maintainers.

You only need to do this once to prepare your environment.

• A recent C++ compiler
• Git installed on your system
• A GitHub account
• A Git client (e.g., GitHub Desktop, GitKraken, or the command line)

1. Fork the Repository: Create your personal copy (a "fork") of the official Stockfish repository.

   • Go to: https://github.com/official-stockfish/Stockfish
   • Click the Fork button in the top-right corner.
   • GitHub Help: Fork a Repo

   

2. Clone Your Fork: Create a local copy of your forked repository on your computer. Use your Git client and the URL from your forked repository page.

This is the cycle you will follow for every new change you want to make.

Before starting any new work, ensure your local master branch is up-to-date with the official Stockfish master. This prevents merge conflicts.

You can use the provided script for convenience or perform the steps manually with Git.

#!/bin/sh

# Change directory to the path of the script
cd "${0%/*}"

# !!! EDIT THIS LINE to point to your local Stockfish src directory !!!
# Example: cd /path/to/your/Stockfish/src
cd ./chess/stockfish/src

echo
echo "Syncing local master branch with official-stockfish/master..."

# Add the official repo as a remote named 'official' if it doesn't exist
git remote add official https://github.com/official-stockfish/Stockfish.git 2>/dev/null
git remote set-url official https://github.com/official-stockfish/Stockfish.git

echo "--> Switching to local 'master' branch..."
git checkout master

echo "--> Fetching latest changes from 'official'..."
git fetch official

echo "--> Resetting local 'master' to match 'official/master'..."
# WARNING: This discards any local changes on your master branch!
git reset --hard official/master

echo "--> Pushing updated 'master' to your GitHub fork ('origin')..."
git push origin master --force

echo "--> Recompiling Stockfish..."
make clean
make build -j
make net

echo
echo "Sync complete."

All work should be done on a dedicated branch, not on master. This keeps your changes isolated.

1. Navigate to your local Stockfish directory in your terminal.
2. Create and switch to a new branch:

   git checkout -b my-new-feature-branch

   (Choose a descriptive name for your branch.)
3. Edit the source code to implement your idea.
4. Compile your changes. You can find detailed instructions at Compiling from source.
5. Commit your changes with a clear message:

   git commit -am "My clear and descriptive commit message"

6. Push the branch to your fork on GitHub:

   git push origin my-new-feature-branch

Once your branch is on GitHub, you can submit it to Fishtest for performance testing.

1. Go to https://tests.stockfishchess.org/tests/run.
2. Base repository: The URL of the official repo: https://github.com/official-stockfish/Stockfish.
3. Base branch: master.
4. Test repository: The URL of your forked repo (e.g., https://github.com/yourname/Stockfish).
5. Test branch: The name of the branch you just pushed (e.g., my-new-feature-branch).
6. Test signature: Get this by running ./stockfish bench in your src folder. It's the number from the Nodes searched line. (Fishtest can often auto-fill this if you include Bench: XXXXXXX in your commit message).
7. Choose a Test Type. For most changes, follow the Standard Testing Methodology.
8. Info: Write a short but descriptive summary of your change.
9. Click Submit test.

How to submit an SPSA test

1. Follow the steps above to set up a new test.
2. In Test options, consider using nodestime for evaluation tuning to reduce hardware noise. A common setting is Hash=128 nodestime=600.
3. Choose an appropriate time control (TC). 60+0.6 is good for final tunes.
4. Paste the comma-separated list you copied from ./stockfish into the SPSA Parameters box.
5. Review the parameters. A good tune should show significant changes in values without being purely random. If values barely change after thousands of games, the ck value may be too low, and the test should be stopped.
6. Submit the test.

[!NOTE] You cannot change the number of games for SPSA tests after they have started, as the tuning parameters depend on the initial game count.

Once your change has passed the required tests and you are confident in it, it's time to create a pull request (PR) to merge it into the official repository.

• ✅ Is your branch up-to-date? Sync your fork and merge the latest master into your feature branch to resolve any conflicts.
• ✅ Is it a single commit? If your branch has multiple messy commits, "squash" them into a single, clean commit.
• ✅ Is the code clean? Ensure your code matches the surrounding style, with no trailing whitespace.
• ✅ Is the commit message high-quality? It should explain the "what" and the "why" of your change. This message becomes the PR description.
• ✅ Did you include test results? Link to the passed STC and LTC tests on Fishtest.
• ✅ Did you include the new bench signature? The last line of your commit message must be either No functional change or Bench: XXXXXXX.
• ✅ Is your patch portable? Your PR will be automatically tested on various compilers via GitHub Actions. You can test this yourself beforehand by pushing your branch to a branch named github_ci on your fork.

Simplify away nnue scale pawn count multiplier

Removes 2x multipliers in nnue scale calculation along with the pawn count term that was recently reintroduced.

Passed non-regression STC:
https://tests.stockfishchess.org/tests/view/64305bc720eb941419bdf72e
LLR: 2.95 (-2.94,2.94) <-1.75,0.25>
Total: 38008 W: 10234 L: 10021 D: 17753

Passed non-regression LTC:
https://tests.stockfishchess.org/tests/view/6430b76a028b029b01ac9bfd
LLR: 2.94 (-2.94,2.94) <-1.75,0.25>
Total: 91232 W: 24686 L: 24547 D: 41999

Bench: 4017320

Set the length of GIT_SHA to 8 characters

Previously, the length of git commit hashes could vary depending on the git environment. This change standardizes it.

No functional change

This section provides guidelines for choosing the correct test parameters on Fishtest. When in doubt, use the Standard procedure.

This is the workhorse for ensuring only robust, Elo-positive patches are merged.

1. Run a test at STC (10+0.1) with standard SPRT bounds [-0.75, 0.75].
2. If the STC test passes, run a new test at LTC (60+0.6) with standard SPRT bounds [0.0, 1.0].
3. If the LTC test passes, you are ready to create a pull request.

These changes aren't expected to gain Elo, so we test them to ensure they don't lose Elo.

• Follow the standard STC -> LTC procedure, but use non-regression SPRT bounds, typically [-1.75, 0.25]. This requires the change to be statistically unlikely to lose more than 1.75 Elo.

Changes that only improve speed (nodes per second) without altering search logic.

1. Benchmark locally first. Use tools like perf on Linux or specialized scripts like pyshbench or FishBench to measure the speedup. A gain of at least 0.5% is typically required to be considered.
2. If the change is complex, it must be tested on Fishtest like a standard functional change, as speedups can have unpredictable effects on search strength. A significant speedup will translate to an Elo gain on Fishtest.

#!/bin/sh
set -e

if [ -z "$1" ]; then
    exit 1
fi

if ! git diff --exit-code --quiet; then
    echo "Working directory is not clean; cannot generate bench" >&2
    exit 0
fi

# Keyword to replace with bench message
ACTIVATION="autobench"

# Look for keyword in commit message to replace
if ! grep -q -- "$ACTIVATION" "$1"; then
    exit 0
fi

# Build Stockfish
cd src
make -j build debug=yes
cd ..

# Obtain signature
signature=$(./src/stockfish bench 2>&1 | grep "Nodes searched  : " | awk '{print $4}')

# Replace keyword with bench message
sed -i "/^${ACTIVATION}\$/c\Bench: $signature" "$1"