Contributing to Windshift

April 13, 2026 · View on GitHub

Thanks for your interest in contributing! See the README for a project overview.

Note: The GitHub repository is a read-only push mirror. All development and contributions happen on Codeberg. Please fork, clone, and open pull requests there.

Prerequisites

  • Go 1.25+
  • Node.js 22+
  • Docker (starts PostgreSQL and other services for local development)

Development Setup

# Clone the repo
git clone https://codeberg.org/realigned/windshift-core.git && cd windshift-core/core

# Install frontend dependencies
cd frontend && npm install && cd ..

# Install git hooks
make hooks

# Start PostgreSQL + dev server (SQLite for main app, PostgreSQL for logbook)
./dev.sh

The dev server runs on localhost:7777.

Git Hooks

The project includes a pre-commit hook that runs golangci-lint and biome check before each commit. Install it with:

make hooks

To bypass the hook for a quick commit, use git commit --no-verify.

For frontend-only development with hot reload:

cd frontend && npm run dev

To run the design system viewer:

cd frontend && npm run ds:dev

For a standalone Go build that includes test utilities:

make dev-build

Project Structure

.
├── internal/          # Go backend
│   ├── handlers/      # HTTP request handlers
│   ├── models/        # Data models
│   ├── services/      # Business logic
│   ├── repository/    # Data access layer
│   └── database/      # Database setup and migrations
├── frontend/          # Svelte 5 / Vite / Tailwind CSS
├── cmd/ws/            # CLI client
└── .github/workflows/ # CI pipelines

Making Changes

  1. Create a feature branch from main.
  2. Keep commits focused and descriptive.

Code Style

Go

The project uses gofmt, goimports, and staticcheck. Lint configuration lives in .golangci.yml.

make lint

Frontend

The project uses Biome (config: frontend/biome.json).

cd frontend
npm run lint        # check
npm run format      # auto-format

Submitting a Pull Request

Please open all pull requests on Codeberg.

  1. Push your branch and open a PR against main.
  2. CI will run automatically:
    • Go: lint + unit tests
    • Frontend: lint, tests, bundle size check
    • PR title lint and merge-conflict check
  3. Describe what changed and why. Reference related issues if applicable.

Contributor License Agreement

By submitting a pull request you agree to the CLA. The project is dual-licensed under the AGPL v3.0 and the Windshift Commercial License.

Code of Conduct

Be respectful, constructive, and collaborative.