Contributing

🤝 Contributing

Bug reports, recipes, and focused pull requests are all welcome.

---

🧰 Prerequisites

• Go 1.26 or newer
• make
• Optional, for regenerating screenshots: python3 with pyte, and bwrap

git clone https://github.com/worxbend/nerd-fonts-installer
cd nerd-fonts-installer
go build ./...

---

✅ The one command that matters

make verify

That runs the same gate CI does:

Step	Command
Module hygiene	go mod tidy -diff
Formatting	gofmt -l cmd internal
Vet	go vet ./...
Lint	golangci-lint run
Tests	go test ./...
Race	go test -race ./...
Build	go build -trimpath
Vulnerabilities	govulncheck ./...
Workflows	actionlint

Narrower targets while iterating:

make test
make test-race
make lint
make fmt
make cover

Important

Tests must pass under -race. The install path is concurrent, and a race that only shows up on a loaded CI runner is the worst kind of flake.

---

🧭 Conventions

Small packages, one job each. See 🏗️ Architecture for the map before adding a new one.

Function-typed dependency seams, not interfaces. The dependencies struct in cmd/nerd-fonts-installer is deliberate. Please do not convert it into an interface hierarchy.

Errors wrap with %w and read as a chain of what was being attempted: install Nerd Font family Hack: download …: 404 Not Found.

Table-driven tests with t.TempDir() for filesystem work and an injected *http.Client for network work. No test should reach the real network.

One validator. Family names go through internal/fontname.Validate. Never add a second copy of that guard — it is a security boundary.

---

📚 Repository docs

File	Purpose
MEMORY.md	Architecture map and the invariants you must not break.
AGENTS.md	Working agreement for AI coding agents and contributors.
CHANGELOG.md	Released changes.

If a change alters architecture, a package boundary, a public contract, an invariant, or the build workflow, update MEMORY.md in the same commit. A stale MEMORY.md is treated as a bug.

---

🌱 Branches and commits

• Branch off main.
• Conventional Commits: feat:, fix:, docs:, refactor:, test:, chore:, security:.
• Keep each commit individually green — small commits that each pass make verify are much easier to review and to revert.

fix: keep the TUI frame within the terminal height

Bubble Tea truncates the top of an oversized frame, which silently ate
the banner's top border on every terminal size.

---

🐞 Filing a good bug report

Include:

1. nerd-fonts-installer --version
2. Your OS and terminal
3. Your config file (redact paths if you like)
4. The output of nerd-fonts-installer --dry-run
5. What you expected, and what happened

Open an issue →

---

📸 Regenerating screenshots

pip install pyte
./scripts/screenshots/refresh.sh

Real runs, captured in a pty and rendered to SVG. bwrap shadows $HOME so nothing lands in your actual font directory. Details in scripts/screenshots/README.md.

---

🌐 The website

The microsite in docs/ is plain HTML, CSS, and JavaScript with no build step. Preview it by assembling the same tree the Pages workflow does:

mkdir -p /tmp/site/assets
cp -R docs/. /tmp/site/
cp -R assets/. /tmp/site/assets/
python3 -m http.server --directory /tmp/site 8000

It deploys automatically on pushes to main that touch docs/ or assets/.

---

Back to: 🏠 Home