Skip to content

Contributing

dlommm edited this page Jul 14, 2026 · 4 revisions

Contributing / Development

How to build GSBS from source, run tests, contribute code, and keep documentation in sync.


Building from source

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 ./client

WebUI assets

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


Running the server locally

export GSBS_SESSION_SECRET="dev-secret-not-for-production"
export GSBS_DB="./gsbs-dev.db"
./gsbs-server

Or use Docker:

docker compose -f docker-compose.dev.yml up --build

Open http://localhost:8080.


Running tests

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

Tests 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

Lint

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=5m

Also run vulnerability scan:

go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...

Code conventions

API and server

  • Add new endpoints in server/api/handler.go; use withAuth for authenticated routes.
  • Keep request/response types in pkg/types when shared across server and client.
  • Add new store methods to server/store/store.go (interface) and implement in server/store/sqlite.go.
  • Always use context.Context on store calls.

Client

  • Never write pulled saves when the target directory does not exist (folder-exists rule).
  • Use pkg/paths.Resolver for all placeholder resolution.
  • Platform-specific code goes in _windows.go / _linux.go files.

Database

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

Documentation

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

Where to work (skills and subagents)

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.


Wiki and documentation

How the wiki works

  • 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 main when files in docs/wiki/, docs/*.md, README.md, or CONTRIBUTING.md change.
  • Push of a version tag (v*) for a release snapshot.
  • Manual: gh workflow run sync-wiki.yml or via Actions → sync-wiki → Run workflow.

Wiki authoring rules

  1. Edit files in docs/wiki/ (not directly on the GitHub Wiki web UI).
  2. Follow the wiki style guide — headings, callouts, internal links, image URLs.
  3. All upgrade procedures must be in Upgrading; other pages link there.
  4. Run the quality checks locally before pushing:
./script/check-wiki.sh

This checks for: required page titles, broken relative links, missing language tags on code blocks, and duplicate upgrade procedures outside Upgrading.md.

Rollback a bad wiki sync

If a sync publishes incorrect content:

  1. Fix the source in docs/wiki/.
  2. Push to main — the sync workflow re-runs automatically.
  3. 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).


Release workflow

The release workflow is documented for maintainers in docs/RELEASE.md. Summary:

  1. Update CHANGELOG.md.
  2. Commit and push to main; wait for CI green.
  3. Push a semver tag: git tag -a vX.Y.Z -m "Release vX.Y.Z" && git push origin vX.Y.Z
  4. The release workflow publishes GitHub Release assets and Docker Hub images.
  5. The sync-wiki workflow publishes a tagged doc snapshot to the wiki.

Security

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.


Related pages

Translations

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.

Clone this wiki locally