> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/TecharoHq/Anubis/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Guidelines for contributing code to Anubis

This guide covers commit message format, code style, and the PR submission process.

## Commit Message Format

All commits **must** follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format:

```text theme={null}
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Commit Types

* `feat`: New feature
* `fix`: Bug fix
* `docs`: Documentation changes
* `style`: Code style changes (formatting, no logic changes)
* `refactor`: Code refactoring (no behavior changes)
* `perf`: Performance improvements
* `test`: Adding or updating tests
* `build`: Build system or dependency changes
* `ci`: CI/CD configuration changes
* `chore`: Maintenance tasks
* `revert`: Revert a previous commit

### Examples

```text theme={null}
feat(policy): add support for CEL expressions in bot matching

fix: resolve event loop thrashing in proof-of-work solver

docs: update installation guide for Go 1.24

refactor(store)!: change Store interface to return errors

BREAKING CHANGE: Store.Get now returns ([]byte, error) instead of []byte
```

### Commit Rules

* Keep descriptions **concise**
* Use **imperative mood** ("add feature" not "added feature")
* Use **lowercase** for descriptions
* **No trailing period**
* Add `!` after type/scope for breaking changes
* Use `BREAKING CHANGE:` in footer for breaking changes
* Reference issues/PRs in footer when applicable

## Signed Commits (REQUIRED)

<Warning>
  **ALL commits MUST be signed with `--signoff`**. This is mandatory and enforced by commitlint.
</Warning>

### Sign Your Commits

Every commit must include a `Signed-off-by` line:

```bash theme={null}
git commit --signoff -m "feat: add new feature"
```

Or use the `-s` shorthand:

```bash theme={null}
git commit -s -m "fix: resolve race condition"
```

### AI Agent Attribution

If you're using an AI coding tool, you **must** disclose it in the commit footer:

```text theme={null}
feat: implement rate limiting for challenge requests

Assisted-by: Claude 4.5 Sonnet via OpenCode
Signed-off-by: Your Name <you@example.com>
```

Format:

```text theme={null}
Assisted-by: [Model Name] via [Tool Name]
```

### Automatic Signoff

Configure Git to sign off commits automatically:

```bash theme={null}
git config --local commit.gpgsign true
```

Or use a Git hook (see `.husky/commit-msg` in the repository).

## Code Style

### Go

Anubis follows Go standard library idioms:

* **Formatting**: Use `goimports` (run `npm run format`)
* **Package aliases**: Only when names collide
* **Naming**:
  * `PublicFunctionsAndTypes` in PascalCase
  * `privateFunctionsAndTypes` in camelCase
  * Acronyms stay uppercase (`URL`, `HTTP`, `IP`, `DNS`)
* **Errors**:
  * Sentinel errors as package-level `Err` prefixed variables
  * Wrap with `fmt.Errorf("package: context: %w", err)`
  * Use `errors.Is` for validation
* **Logging**:
  * Use `log/slog` for structured logging
  * Pass loggers as function arguments
  * Prefer `slog.Debug` unless users need to see the message
* **Configuration**:
  * Use both `json` and `yaml` struct tags
  * Use pointer values for optional fields
  * Validate with `Valid() error` methods
* **Tests**:
  * Use table-driven tests
  * Use `t.Helper()` in helper functions
  * Use `t.Cleanup()` for teardown
  * Prefer same-package tests over `_test` packages

### JavaScript/TypeScript

* Source in `web/js/`
* Built with esbuild
* Uses **Preact** (not React)
* Use `const` by default
* Keep functions small
* No linter config - rely on code review

### Templ Templates

* `.templ` files in `web/` generate Go code
* Run `npm run assets` after modifying
* Keep logic in Go, not templates
* Templates receive typed Go parameters

## Pull Request Process

### Before Submitting

1. **Build assets**:
   ```bash theme={null}
   npm run assets
   ```

2. **Run tests**:
   ```bash theme={null}
   npm run test
   npm run test:integration
   ```

3. **Run linting**:
   ```bash theme={null}
   npm run lint
   ```

4. **Format code**:
   ```bash theme={null}
   npm run format
   ```

5. **Update CHANGELOG**:
   Add your changes to `[Unreleased]` in `docs/docs/CHANGELOG.md`

### PR Checklist

* [ ] All commits follow Conventional Commits format
* [ ] All commits are signed with `--signoff`
* [ ] All commits have verified (signed) signatures
* [ ] Tests added for bug fixes and new features
* [ ] Integration tests pass (`npm run test:integration`)
* [ ] CHANGELOG updated in `docs/docs/CHANGELOG.md`
* [ ] AI tool attribution added if applicable
* [ ] Code follows project style guidelines

### Creating the PR

1. **Push your branch**:
   ```bash theme={null}
   git push origin feature/my-feature
   ```

2. **Open PR** on GitHub

3. **Fill out template** (see `.github/PULL_REQUEST_TEMPLATE.md`)

4. **Request review**

### PR Review

Anubis is **security software** - code reviews are strict:

* Security implications are carefully evaluated
* Test coverage is required
* Adversarial inputs are considered
* Breaking changes require discussion

## Security Considerations

<Warning>
  Anubis is security software. All contributions must consider adversarial scenarios.
</Warning>

### Security-First Principles

* **Input validation**: Validate all external input
* **Error handling**: Don't leak internal state in error messages
* **Rate limiting**: Consider DoS scenarios
* **Cryptography**: Use standard library crypto packages
* **Dependencies**: Minimize external dependencies

### Reporting Security Issues

See `SECURITY.md` for the security policy and reporting process.

## Key Conventions

### Configuration

* YAML-based policy files
* Config structs validate via `Valid() error` returning sentinel errors
* See `lib/config/` for examples

### Store Interface

* `lib/store.Interface` abstracts key-value storage
* Implementations in `lib/store/`
* Always handle errors from Store operations

### Environment Variables

* Parsed from flags via `flagenv`
* Use `.env` files locally (loaded by `godotenv/autoload`)
* **NEVER commit `.env` files**

### Asset Building

* JS/CSS assets embed into Go binary
* **Always run `npm run assets` before `go test` or `go build`**
* Generated files are committed to the repo

### CEL Expressions

* Policy rules support Common Expression Language
* See `lib/policy/expressions/` for implementation
* Use for advanced bot matching rules

## Project Layout

Key directories:

* `cmd/anubis/` - Main entrypoint
* `lib/*/` - Public library code (no API stability guarantees)
* `internal/*/` - Private implementation code
* `test/*/` - Smoke tests
* `web/` - Frontend templates
* `xess/` - CSS framework

## Getting Help

* Open an [issue](https://github.com/TecharoHQ/anubis/issues) for bugs
* Join [Patreon](https://patreon.com/cadey) for live chat in `#anubis` Discord channel
* Read the [documentation](https://anubis.techaro.lol)