126 lines
3.2 KiB
Markdown
126 lines
3.2 KiB
Markdown
|
# 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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
go run ./cmd run
|
||
|
|
```
|
||
|
|
|
||
|
|
Run on another address:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
go run ./cmd run --addr :3000
|
||
|
|
```
|
||
|
|
|
||
|
|
## Tests and Checks
|
||
|
|
|
||
|
|
Run tests:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
./test.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
Run formatting, vet, and tests:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
./check.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
Both scripts honor `GO_BIN`:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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:
|
||
|
|
|
||
|
|
```text
|
||
|
|
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:
|
||
|
|
|
||
|
|
```text
|
||
|
|
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](DEVELOPMENT.md) for cleanup rules.
|