WarpBox/CONTRIBUTING.md

Contributing to WarpBox

WarpBox is a small Go application with server-rendered HTML, vanilla JavaScript, static CSS, local filesystem storage, and BadgerDB metadata. Keep changes boring, readable, and easy to review.

Setup

Requirements:

• Go 1.23 or newer, matching go.mod.
• No frontend toolchain. Do not add npm, Vite, React, TypeScript, Sass, Tailwind, or a JavaScript build step for cleanup work.

Run the app:

go run ./cmd run

Run on another address:

go run ./cmd run --addr :3000

Tests and Checks

Run tests:

./test.sh

Run formatting, vet, and tests:

./check.sh

Both scripts honor GO_BIN:

GO_BIN=/path/to/go ./check.sh

If a command cannot run in your environment, say why and include the command that should be run locally.

Commit Style

Use Conventional Commits:

type(scope): short imperative subject

Types:

• feat user-visible feature
• fix bug fix
• refactor behavior-preserving code change
• test tests only
• docs documentation only
• style formatting or CSS-only visual style when behavior unchanged
• chore tooling, dependency, build, housekeeping
• perf performance change
• ci CI config

Rules:

• Keep subject at 72 characters or less, preferably 50 or less.
• Use imperative mood.
• Keep one concern per commit.
• Make cleanup commits behavior preserving unless the subject says fix.
• Mention tests run in the PR description or commit body when useful.

Examples:

docs(contributing): add cleanup rules
refactor(server): split upload handlers
fix(config): reject negative expiry values

Code Review Expectations

Reviews should focus on behavior, safety, and maintainability:

• Confirm routes, environment variables, API response shapes, manifest fields, and storage layout remain compatible unless the change explicitly updates them.
• Check that cleanup keeps behavior unchanged and is small enough to review.
• Prefer narrow helpers and clear file ownership over clever abstraction.
• Ask for tests when behavior changes or risk is not obvious.
• Call out missing checks, unclear edge cases, concurrency risks, and security risks.

PR Checklist

Before opening or merging a PR:

• Scope is limited to one concern.
• Runtime behavior is unchanged for cleanup PRs.
• Public routes are unchanged unless intentional.
• Environment variables are unchanged unless intentional.
• API response shapes are unchanged unless intentional.
• Manifest JSON field names are unchanged unless intentional.
• Storage directory layout is unchanged unless intentional.
• No frontend build tooling was added.
• Tests or checks run are listed.

Coding Standards Summary

• Go: small functions, clear errors, stable exported names, no unrelated package moves.
• JavaScript: vanilla browser scripts, no build step, explicit state ownership, small modules when files are split.
• CSS: keep shared styles shared, page styles page-scoped, avoid duplicated popup/window rules.
• Templates: keep server-rendered HTML simple and routes stable.
• Comments: explain behavior rules, edge cases, concurrency, security, or product choices. Do not restate obvious code.

See DEVELOPMENT.md for cleanup rules.