Contributing to Mellow

Contributions are welcome. Mellow is written in Go and licensed under AGPL-3.0.

Ways to contribute

Bug fixes and reliability improvements
New or improved coping tools
Crisis-screening improvements (with care - see below)
Accessibility and inclusive language
Documentation
Translations

Development setup

Prerequisites

Go 1.26+
Docker (for a local PostgreSQL), or your own PostgreSQL
sqlc and the migrate CLI if you touch the database layer

Steps

git clone https://github.com/CodeMeAPixel/Mellow.git
cd Mellow

make pg-up          # throwaway Postgres on :5432
cp .env.example .env # fill in TOKEN, CLIENT_ID, ANTHROPIC_API_KEY, ENCRYPTION_KEY

make run

Point TOKEN / CLIENT_ID at a test Discord application with all privileged intents off.

Project layout

See

Architecture

How Mellow is put together.

for the package map. In short: cmd/mellow is the entry point, internal/discord is the bot, internal/ai is the Claude layer, internal/db is the data layer (sqlc + migrations), internal/server is the HTTP API.

House style

No comments unless strictly necessary to explain non-obvious behaviour. The code should read without them.
No em dashes in code or output strings.
Run gofmt (CI fails on unformatted files).
Keep functions small; return errors, do not panic in request paths.
Match the surrounding code's naming and structure.

Database changes

Add a new migration pair in internal/db/migrations (NNNN_name.up.sql / .down.sql). Guard DDL with IF NOT EXISTS where sensible.
Add or edit SQL in internal/db/queries.
Run sqlc generate and commit the regenerated internal/db/gen.
Wrap new sensitive fields with encryption in store.go.

Crisis-screening changes

Crisis handling is deliberately constrained. Before changing it:

Keep the local keyword/regex screen conservative; avoid false negatives on clear intent.
Do not let free-form model output drive high/critical responses.
Update internal/ai/crisis_test.go and
Crisis Safety
Crisis Safety
How Mellow screens for crisis and why it responds the way it does.
.

Checks before a PR

go vet ./...
go build ./...
go test ./...
gofmt -l .          # must print nothing

CI runs the same, plus a Docker build.

Pull requests

One focused change per PR.
Describe what changed and why. Link an issue if there is one.
Update the docs in mellow-site/content/docs if behaviour changed.

Security

Report vulnerabilities privately to [email protected] or via a GitHub security advisory. Do not open a public issue.

Contributing

On this page