Skip to content

development.md

Latest commit

 

History

History
138 lines (103 loc) · 4.04 KB

development.md

File metadata and controls

138 lines (103 loc) · 4.04 KB

Development

This guide covers the tools, setup, and conventions needed to work on nats-server.

Prerequisites

Install tools using mise:

mise install
  • Go — nats-server is written in Go. We always support the latest two major Go versions, so make sure your version is recent enough.
  • Node.js — Required as a runtime for documentation tooling.
  • Bun — JavaScript package manager used for Prettier and documentation formatting.
  • just — Task runner used for building, testing, formatting, and other development workflows. Install with brew install just.

Claude Code

If you use Claude Code for development, install these plugins from the default marketplace:

/plugin install commit-commands@claude-plugins-official
/plugin install superpowers@claude-plugins-official
  • commit-commands — provides /commit and /commit-push-pr slash commands that follow the project's commit conventions automatically.
  • superpowers — provides structured workflows for planning, TDD, debugging, code review, and git worktree isolation.

Setup

Fetch shared justfiles and install all dependencies:

just fetch
just deps

Code style

Go

Go code should be formatted by gofumpt and linted using golangci-lint. This style is enforced by CI.

just go::fmt-check   # Check formatting
just go::fmt         # Auto-fix formatting
just go::vet         # Run linter

Documentation

Markdown files are formatted with Prettier via Bun. This style is enforced by CI.

just docs::fmt-check   # Check formatting
just docs::fmt         # Auto-fix formatting

Testing

just test           # Run all tests (lint + unit + coverage)
just go::unit       # Run unit tests only
just go::unit-cov   # Generate coverage report
go test -run TestName -v ./pkg/server/...  # Run a single test

Test file conventions

  • Public tests: *_public_test.go in test package (package server_test) for exported functions.
  • Internal tests: *_test.go in same package (package server) for private functions.
  • Use testify/suite with table-driven patterns.
  • One suite method per function under test. All scenarios for a function (success, error codes, transport failures, nil responses) belong as rows in a single table — never split into separate TestFoo, TestFooError, TestFooNilResponse methods.
  • Use golang/mock for mocking interfaces.

Before committing

Run just ready before committing to ensure generated code, package docs, formatting, and lint are all up to date:

just ready

Branching

All changes should be developed on feature branches. Create a branch from main using the naming convention type/short-description, where type matches the Conventional Commits type:

  • feat/add-retry-logic
  • fix/null-pointer-crash
  • docs/update-api-reference
  • refactor/simplify-handler
  • chore/update-dependencies

When using Claude Code's /commit command, a branch will be created automatically if you are on main.

Commit messages

Follow Conventional Commits with the 50/72 rule:

  • Subject line: max 50 characters, imperative mood, capitalized, no period
  • Body: wrap at 72 characters, separated from subject by a blank line
  • Format: type(scope): description
  • Types: feat, fix, docs, style, refactor, perf, test, chore
  • Summarize the "what" and "why", not the "how"

Try to write meaningful commit messages and avoid having too many commits on a PR. Most PRs should likely have a single commit (although for bigger PRs it may be reasonable to split it in a few). Git squash and rebase is your friend!