Code Contribution Guidelines

Relevant source files

Purpose and Scope

This document outlines the requirements and best practices for contributing code to the Syncthing project. It covers the Developer Certificate of Origin (DCO) requirement, commit message formatting, coding style conventions, testing expectations, and the pull request workflow. Syncthing is a continuous file synchronization program with strict goals regarding data safety and security README.md9-28

Developer Certificate of Origin (DCO)

All contributions to Syncthing must include a Developer Certificate of Origin sign-off. This certifies that you have the right to submit the code under the project's open source license.

DCO Text

The DCO states that by making a contribution, you certify:

The contribution was created in whole or in part by you and you have the right to submit it under the open source license indicated in the file.
The contribution is based upon previous work covered under an appropriate open source license and you have the right to submit modifications under the same license.
The contribution was provided directly to you by someone who certified (1), (2), or (3) and you have not modified it.
You understand the contribution is public and a record of it (including personal information) is maintained indefinitely.

The full text is available at CONTRIBUTING.md88-108

Sign-off Format

Every commit message must include a Signed-off-by line with your real name and email address:

The name and email must match:

Your git configuration (git config user.name and git config user.email).
The committing author metadata.
Your entry in the AUTHORS file CONTRIBUTING.md112-121

Example Configuration:

Pseudonyms or nicknames are acceptable if you prefer not to use your legal name, but you must be reachable at the provided email address CONTRIBUTING.md70-73

Sources: CONTRIBUTING.md60-121

Authorship and Attribution

AUTHORS File

When your first pull request is accepted, your details are added to the AUTHORS file and the list of authors in the GUI CONTRIBUTING.md62-64 All subsequent commits must use the same name and email as listed in this file CONTRIBUTING.md64-66

First-Time Contributors

Before making your first commit:

Ensure your git configuration is set correctly with your desired name and email CONTRIBUTING.md66-69
Verify the configuration will match what you want in the AUTHORS file.
Make your commit with the sign-off line CONTRIBUTING.md112-117
Submit your pull request.

Sources: CONTRIBUTING.md60-73 CONTRIBUTING.md112-117

Commit Message Format

Conventional Commits

Syncthing uses the Conventional Commits specification for commit messages and pull request titles. All subjects must be in lower case CONTRIBUTING.md147-149

Message Structure

Commit Message Structure:

Type and Scope

The project uses a strict set of types (e.g., feat, fix, docs, chore, refactor, build) enforced by policy bots .policy.yml32-38

The scope indicates the component affected. This typically corresponds to the part after internal/, lib/, or cmd/ in the package path CONTRIBUTING.md151-155:

gui - Web interface changes.
protocol - Block Exchange Protocol.
scanner - File scanner.
db - Database layer (e.g., internal/db/sqlite).
dialer - Connection management.

Omit the scope for changes affecting many components or non-code changes like the build system CONTRIBUTING.md155-157

Issue References

If the commit resolves an existing issue, include (fixes #<number>) at the end of the subject line CONTRIBUTING.md159-161

Example: feat(dialer): add env var to disable proxy fallback (fixes #3006) CONTRIBUTING.md163

Sources: CONTRIBUTING.md145-168 .policy.yml32-38

Coding Style

General Guidelines

Line Endings:

All text files use Unix line endings (LF) CONTRIBUTING.md126

Brace Style:

Follow the brace and parenthesis style of the surrounding code CONTRIBUTING.md129-130

Go-Specific Guidelines

Code Formatting:

All code must be go fmt clean CONTRIBUTING.md140
The project also uses gofumpt for stricter formatting .golangci.yml87

Code Guidelines:

Follow Effective Go and Go Code Review Comments CONTRIBUTING.md134-138

Import Grouping: Imports are grouped per goimports standard: standard library first, then third-party libraries after a blank line CONTRIBUTING.md142-144

Code Quality Tools (`golangci-lint`)

The project uses a comprehensive .golangci.yml configuration. Many linters are enabled by default, while some are explicitly disabled for the Syncthing context (e.g., gochecknoglobals, funlen, cyclop) .golangci.yml4-44

Linter Exclusions:

Context checks are ignored for SQLite operations as they are irrelevant there .golangci.yml67-69
Rollback errors can be ignored .golangci.yml70-72
Generated code and third-party directories are excluded from most linting .golangci.yml54-62

Sources: CONTRIBUTING.md122-144 .golangci.yml1-97

Testing Requirements

Add tests when adding features or fixing bugs CONTRIBUTING.md181-182

Test Organization

Unit Tests: Located within the package they test (e.g., internal/db/sqlite/db_test.go).
Integration Tests: Located in the test/ directory.

Code Entity to Test Association

Sources: CONTRIBUTING.md179-182 internal/db/typed.go18-53

Pull Request Workflow

Contribution Process

Issue: Ensure an issue exists describing the change CONTRIBUTING.md52-55
Branch: Fork and make changes in a new branch CONTRIBUTING.md57-58
Commits: Add commits with corrections during review. Do not rebase, as it makes review harder CONTRIBUTING.md169-172
Review: Maintainers or contributors will review the PR .policy.yml58-63
Merge: PRs are merged to main using squash merge. The PR title and description become the final commit message CONTRIBUTING.md174-177

Approval Policy

The project uses policy-bot to enforce merge requirements:

Conventional Commit Title: Required for all PRs .policy.yml32-38
Maintainer Approval: Required for changes to project metadata (e.g., .md files, LICENSE, .policy.yml) .policy.yml42-52
Contributor Approval: Required for regular PRs .policy.yml58-63
Trivial Changes: PRs with < 25 modified lines and the trivial label may be accepted on trust if proposed by a contributor .policy.yml92-103

Contribution Flow:

Sources: CONTRIBUTING.md43-59 CONTRIBUTING.md169-178 .policy.yml1-114

Licensing

MPLv2 License

All code is licensed under the Mozilla Public License Version 2.0 (MPLv2) README.md95 By contributing, you agree to the terms of the MPLv2 LICENSE1-374

Authorship Attribution

When your PR is accepted, your name/email (as configured in git) is added to the AUTHORS file and displayed in the GUI CONTRIBUTING.md62-64

Sources: README.md95 LICENSE1-374 CONTRIBUTING.md60-73

Bug Reporting

File bugs in the GitHub Issue Tracker CONTRIBUTING.md3-4

Include:

OS and Syncthing versions for all involved devices CONTRIBUTING.md12-15
Screenshots for GUI issues CONTRIBUTING.md17
Console logs where relevant CONTRIBUTING.md19

Security Vulnerabilities: Do NOT report these publicly. Email security@syncthing.net README.md72-74

Sources: CONTRIBUTING.md1-23 README.md66-74