Repository navigation
Contributing
How to build GSBS from source, run tests, contribute code, and keep documentation in sync.
Requirements:
- Go 1.25+
- Node.js (for WebUI CSS compilation via Tailwind)
- CGO enabled (default; required for SQLite)
- Linux build deps:
gcc(cgo, for the SQLite server build — the tray client is pure Go)
git clone https://github.com/dlommm/GSBS-Game-Sync-Backup-Service.git
cd GSBS-Game-Sync-Backup-Service
go mod tidy
./script/build-webui.sh # compile Tailwind CSS (requires Node.js)
go build -o gsbs-server ./server
go build -o gsbs-client ./clientAfter changing templates or server/webui/static/src/input.css, rebuild assets:
./script/build-webui.sh
go run ./cmd/gen-branding # regenerates all icons/branding from assets/images/script/release.sh runs build-webui.sh automatically before building server binaries.
export GSBS_SESSION_SECRET="dev-secret-not-for-production"
export GSBS_DB="./gsbs-dev.db"
./gsbs-serverOr use Docker:
docker compose -f docker-compose.dev.yml up --buildOpen http://localhost:8080.
go test ./server/... ./pkg/... ./client/...With race detector and coverage (matches CI):
go test -race -coverprofile=coverage.out ./server/... ./pkg/... ./client/...
go tool cover -func=coverage.outTests use an in-memory SQLite database (:memory:) where possible. Key test files:
| File | Covers |
|---|---|
server/auth/auth_test.go |
Auth, tokens, 2FA |
server/store/sqlite_test.go |
Store interface, migrations |
server/api/handler_test.go |
API endpoints |
client/update_test.go |
Update check logic |
CI runs golangci-lint with config in .golangci.yml. Run locally before pushing:
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
golangci-lint run --timeout=5mAlso run vulnerability scan:
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...- Add new endpoints in
server/api/handler.go; usewithAuthfor authenticated routes. - Keep request/response types in
pkg/typeswhen shared across server and client. - Add new store methods to
server/store/store.go(interface) and implement inserver/store/sqlite.go. - Always use
context.Contexton store calls.
- Never write pulled saves when the target directory does not exist (folder-exists rule).
- Use
pkg/paths.Resolverfor all placeholder resolution. - Platform-specific code goes in
_windows.go/_linux.gofiles.
- Add schema changes as a new migration step using
PRAGMA user_version. - Write the migration idempotently; test against an existing DB in
sqlite_test.go. - Document the migration in the
[Upgrading](Upgrading)wiki page.
- Update docs/ARCHITECTURE.md for data model or sync flow changes.
- Update docs/API.md for API endpoint changes.
- Wiki pages in
docs/wiki/are the published docs — update them when behavior changes. See the wiki style guide. - All upgrade instructions must go in Upgrading; other pages must link there.
The project uses Cursor skills and subagents to scope AI-assisted work:
| Focus | Skill / subagent | Key paths |
|---|---|---|
| Server API, auth, store, WebUI, jobs | gsbs-server |
server/, server/api/handler.go, server/store/, server/webui/
|
| Client sync, watcher, config, tray, list | gsbs-client |
client/, client/sync/, client/config.go
|
| PCGW, path resolution, placeholders, manifest | gsbs-pcgw-paths |
pkg/pcgw/, pkg/paths/, server/job/pcgw.go
|
| Build, release script, Docker, version | gsbs-release |
script/release.sh, Dockerfile, docs/DOCKER.md
|
Skills: .cursor/skills/<name>/SKILL.md. Subagents: .cursor/agents/<name>.md.
When you change behavior in any area, update the matching skill and subagent so future agents stay accurate.
-
docs/wiki/in the repository is the canonical authoring source for all wiki pages. - The GitHub Wiki (
*.wiki.git) is the published view — automatically synced by.github/workflows/sync-wiki.yml.
Sync triggers:
- Push to
mainwhen files indocs/wiki/,docs/*.md,README.md, orCONTRIBUTING.mdchange. - Push of a version tag (
v*) for a release snapshot. - Manual:
gh workflow run sync-wiki.ymlor via Actions → sync-wiki → Run workflow.
- Edit files in
docs/wiki/(not directly on the GitHub Wiki web UI). - Follow the wiki style guide — headings, callouts, internal links, image URLs.
- All upgrade procedures must be in Upgrading; other pages link there.
- Run the quality checks locally before pushing:
./script/check-wiki.shThis checks for: required page titles, broken relative links, missing language tags on code blocks, and duplicate upgrade procedures outside Upgrading.md.
If a sync publishes incorrect content:
- Fix the source in
docs/wiki/. - Push to
main— the sync workflow re-runs automatically. - Or manually trigger:
gh workflow run sync-wiki.yml.
The GitHub Wiki web UI can also be used to revert to a previous revision (wiki pages have revision history).
The release workflow is documented for maintainers in docs/RELEASE.md. Summary:
- Update
CHANGELOG.md. - Commit and push to
main; wait for CI green. - Push a semver tag:
git tag -a vX.Y.Z -m "Release vX.Y.Z" && git push origin vX.Y.Z - The release workflow publishes GitHub Release assets and Docker Hub images.
- The sync-wiki workflow publishes a tagged doc snapshot to the wiki.
Do not open public GitHub issues for security vulnerabilities.
Report security issues privately by emailing the maintainer (contact on the GitHub profile). Include:
- Description of the issue
- Steps to reproduce
- Impact assessment
- Suggested fix (optional)
We aim to acknowledge reports within 72 hours.
English is the source of truth in pkg/i18n/locales/en.json. Add a language by copying it to pkg/i18n/locales/<code>.json, translating the values (keys unchanged; missing keys fall back to English; keep {0}/{1} placeholders). The new language then appears in Settings → Language. Run go test ./pkg/i18n/ — it fails if a translation defines a key that English doesn't have.
Getting started
Reference
Help
Contributing