# Contributing

Thanks for contributing to Moku Work.

This project is still in an early scaffold stage, so the goal is to keep changes easy to understand, easy to review, and easy to undo.

## Getting Started

### Project structure

- `Frontend/` — SolidStart frontend workspace
- `Backend/` — Go backend services (`web`, `api`, `worker`)
- `Proxy/` — local production proxy/runtime assets
- `Docker/` — local Docker Compose files
- `Env/` — local environment files
- `Commands/` — Just command modules and entrypoints

### Prerequisites

Before working on the project, make sure you have:

- `just`
- Docker with `docker compose`
- Docker Buildx
- Node.js `>=22`
- `pnpm@9`

### Local development

List available commands:

```bash
just --list --list-submodules
```

Main local development flow:

```bash
just local dev
```

This command builds the frontend and backend development images, then starts the
local development stack for Postgres, Valkey, frontend, and backend services.

### Local environment

Local development uses:

```bash
Env/.env.local
```

The template lives at:

```bash
Env/.env.example
```

When you start the local Docker stack, the dev scripts will create `Env/.env.local`
from `Env/.env.example` automatically if it does not already exist.

If you need custom local values, edit `Env/.env.local` after it is created.

## Commit Naming Convention

Use short, clear commit messages that describe one logical change.

Preferred format:

```text
Type: Short description
```

Examples:

```text
Feat: Add login page scaffold
Fix: Resolve mobile sidebar overflow
Refactor: Split theme helpers from app entry
Docs: Add local development notes
Chore: Update frontend dependencies
```

Recommended commit types:

- `Feat:` — new feature or visible behavior
- `Fix:` — bug fix
- `Refactor:` — internal code change without behavior change
- `Docs:` — documentation only
- `Chore:` — maintenance, tooling, dependency, or housekeeping work
- `Style:` — formatting or styling-only cleanup
- `Test:` — tests added or updated

### Commit message rules

- Keep the subject line short and specific
- Start with a capitalized type
- Describe what changed, not the entire session
- One commit should usually be explainable in one sentence

Good:

```text
Feat: Add base dashboard layout
Fix: Correct broken theme toggle import
Docs: Document branch naming workflow
```

Bad:

```text
stuff
more updates
big rewrite
misc fixes
```

## Branch Naming Convention

Use branch names that make the purpose of the work obvious at a glance.

Preferred format:

```text
type/short-description
```

Examples:

```text
feature/login-page
fix/mobile-sidebar-overflow
refactor/theme-helpers
docs/contributing-update
chore/frontend-dependency-updates
rewrite/v2-foundation
```

Recommended branch types:

- `feature/` — new feature work
- `fix/` — bug fixes
- `refactor/` — structural code changes without intended behavior changes
- `docs/` — documentation work
- `chore/` — maintenance or tooling updates
- `rewrite/` — large rebuilds or architecture overhauls

### Branch naming rules

- Use lowercase words
- Separate words with hyphens
- Keep the name short but specific
- Name the branch after the outcome, not the time spent on it
- For larger efforts, prefer one clear branch name over vague labels like `misc` or `updates`

Good:

```text
feature/auth-shell
fix/docker-local-env-loading
rewrite/new-routing-foundation
```

Bad:

```text
new-stuff
work-branch
test
misc-updates
```