Thank you for your interest in contributing to ɳSelf. This guide covers everything from filing a bug report to landing a complex feature.

• Read the Code of Conduct. All contributors are expected to follow it.
• Read the Governance model, it explains how decisions get made.
• Check open issues and Discussions before opening a new one.

1. Search existing issues first. Your bug may already be tracked.
2. Open a new issue using the Bug Report template.
3. Include: ɳSelf version (nself version), OS, Docker version, exact steps to reproduce, and actual vs expected behaviour.
4. Attach relevant logs: nself logs or nself doctor.

1. Check existing feature requests.
2. Open a new issue using the Feature Request template.
3. Describe the use case, not just the solution. This helps evaluate alternatives.
4. For significant changes, start a Discussion first.

• Go 1.22 or later (go version)
• GNU Make
• Docker + Docker Compose (for integration tests)
• golangci-lint (optional but recommended: brew install golangci-lint)

git clone https://github.com/nself-org/cli.git
cd cli
make build          # builds ./nself binary
make test           # runs all unit tests (no Docker required)
make install        # installs binary to /usr/local/bin/nself

Integration tests require a running Docker environment:

INTEGRATION=1 make test

This repo vendors all Go dependencies. After changing go.mod:

go mod vendor
git add vendor/

Always branch from main. Target main in your PR.

# 1. Fork and clone
git clone https://github.com/YOUR-USERNAME/cli.git
cd cli

# 2. Create a branch
git checkout -b feat/my-feature

# 3. Make changes, then verify
make test
make vet
gofmt -l .          # must produce no output

# 4. Commit with a conventional message
git commit -m "feat: add my feature"

# 5. Push and open a PR
git push origin feat/my-feature

• Fill in the PR template completely.
• All CI checks must pass before review.
• One review from a CODEOWNER is required to merge (see CODEOWNERS).

• Format: gofmt, run via make fmt. CI fails on unformatted code.
• Lint: golangci-lint run must pass with zero warnings.
• Tests: all existing tests must pass. New features need matching tests.
• Errors: wrap with context, fmt.Errorf("doing X: %w", err).
• Context: accept context.Context as first parameter in I/O functions.
• No panics in production code paths. No os.Exit() outside main.go.
• User output: use internal/ui, not fmt.Println directly.

The CLI has package-level coverage floors enforced by the Coverage workflow. New code in these packages must keep the package above its floor or CI will fail.

Run coverage locally before pushing:

go test -mod=vendor -coverprofile=coverage.out ./...
go tool cover -func=coverage.out | tail -1
go tool cover -func=coverage.out | grep "internal/trust"   # per-package

Floor changes need a PR with a justification line in the workflow comment. Path A (write tests) is preferred over Path B (lower the floor) per the CI/CD 100% Green Hard Rule.

Use Conventional Commits:

• feat:, new feature
• fix:, bug fix
• chore:, maintenance (deps, CI)
• docs:, documentation only
• test:, tests only
• refactor:, no behaviour change

Breaking changes: add ! after type (feat!:) and document in the PR body.

The CLI loads plugins from plugins/ (free) and plugins-pro/ (paid). To add or modify a plugin:

1. Read .claude/docs/PLUGIN_SYSTEM_SPEC.md, plugin manifest schema and loader pipeline.
2. Create or update the plugin directory with a valid plugin.json manifest.
3. Add integration tests that verify nself plugin install <name> succeeds.
4. File a PR to the plugins repo, not to cli (unless you are changing the plugin loader itself).

See Plugin Dev Guide for the complete walkthrough.

Do not open a public issue for security vulnerabilities. Follow the process in SECURITY.md.

The CLI's internationalisation strategy is under review. Translation contributions are deferred until the strategy decision is documented. Watch Discussions for updates.

• GitHub Discussions, preferred for questions
• Community: nself.org

• GOVERNANCE.md, decision model
• ENFORCEMENT.md, code of conduct enforcement
• CODEOWNERS, who reviews what
• Dev-Setup, local environment setup
• Plugin-Dev-Guide, building a new plugin
• Release-Process, release workflow

← Home | _Sidebar