Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
157 lines (108 loc) · 4.17 KB

CONTRIBUTING.md

File metadata and controls

157 lines (108 loc) · 4.17 KB

Contributing to Hooks

Thanks for your interest in contributing! This guide covers local development setup for working on the Go server and templates.

If you just want to run Hooks, see the README -- it's a single docker compose up --build.

Prerequisites

Setup

  1. Fork and clone the repository:
git clone https://github.com/<your-username>/hooks.git
cd hooks
  1. Download the Tailwind CSS standalone CLI and start the database:
make setup
docker compose up db -d
  1. Run the server:
make dev

This builds CSS, starts a Tailwind file watcher in the background, and runs the Go server. The watcher rebuilds CSS automatically when you change templates.

  1. Open http://localhost:8080.

Using your own Postgres

You don't have to use the Docker Postgres. Copy the example env file and configure it:

cp .env.example .env

Then edit .env with your connection details:

# Option 1: Full connection string
DATABASE_URL=postgres://user:pass@localhost:5432/hooks?sslmode=disable

# Option 2: Individual variables
DB_HOST=localhost
DB_USER=myuser
DB_PASSWORD=mypass
DB_NAME=hooks
DB_SSLMODE=disable

The Makefile loads .env automatically. The server runs migrations on startup, so you just need an empty database.

Running Tests

make test

Tests run against unit-testable code and do not require a running database.

Database & Migrations

Migrations live in internal/db/migrations/ and use Goose. They run automatically every time the server starts.

To check migration status or roll back manually:

make migrate-status
make migrate-down

To reset the database entirely (e.g. after changing an existing migration during development):

docker compose down -v
docker compose up db -d

Then restart the server and migrations will re-run from scratch.

Project Structure

hooks/
├── cmd/server/          # Entry point, router, embedded static assets
├── internal/
│   ├── handler/         # HTTP handlers and HTML templates (inline in Go files)
│   ├── db/              # Postgres queries and migrations
│   ├── cleanup/         # Background expiry job
│   └── middleware/       # Rate limiting, CORS
├── input.css            # Tailwind v4 source
├── docker-compose.yml
├── Dockerfile
└── Makefile

Makefile Reference

Command Description
make setup Download the Tailwind CSS standalone CLI for your platform
make dev Build CSS, start Tailwind watcher, run the Go server
make build Compile binary to bin/hooks
make test Run all tests
make css One-off Tailwind CSS build (no minification)
make css-watch Tailwind CSS watch mode (no minification)
make update-htmx Download latest vendored HTMX

Making Changes

  1. Create a branch from main:
git checkout -b my-change

  1. Make your changes and add tests where applicable.

  2. Run the full check:

make test
go build ./...

  1. Commit with a clear message describing what and why.

  2. Open a pull request against main.

Code Style

  • Follow standard Go conventions (gofmt).
  • HTML templates are inline in handler Go files -- no separate template files.
  • Tailwind CSS v4 compiled via the standalone CLI. The Docker build handles minification for production.

What to Contribute

  • Bug fixes
  • Performance improvements
  • New response presets or inspector features
  • Documentation improvements
  • Test coverage

If you're planning a large change, open an issue first to discuss the approach.

License

By contributing, you agree that your contributions will be licensed under the MIT License.