# Contributing to Jido Character

Thank you for your interest in contributing to Jido Character! This guide outlines the expectations and requirements for contributions.

## Table of Contents

- [Core Principles](#core-principles)
- [Development Setup](#development-setup)
- [Testing Requirements](#testing-requirements)
- [Code Quality Standards](#code-quality-standards)
- [Commit Message Convention](#commit-message-convention)
- [Pull Request Process](#pull-request-process)
- [Questions?](#questions)

## Core Principles

Jido Character provides extensible character definitions for AI agents. We value:

1. **Immutability**: All character updates return new maps; old versions are preserved
2. **Quality Over Speed**: Code must pass all quality checks before review
3. **Conventional Commits**: All commits must follow the conventional commits specification
4. **Test Coverage**: >90% coverage required, new features require comprehensive tests

## Development Setup

```bash
# Clone the repository
git clone https://github.com/agentjido/jido_character.git
cd jido_character

# Install dependencies and git hooks
mix setup

# Verify setup
mix test
mix quality
```

### Git Hooks

We use [`git_hooks`](https://hex.pm/packages/git_hooks) to enforce commit message conventions:

```bash
mix git_hooks.install
```

This installs a `commit-msg` hook that validates your commit messages follow the conventional commits specification.

## Testing Requirements

```bash
# Run all tests
mix test

# Run tests with coverage
mix coveralls

# Run specific test file
mix test test/jido_character/your_test.exs
```

### Coverage Requirements

- Minimum 90% line coverage required
- New features must include comprehensive tests
- Edge cases and error paths should be covered

## Code Quality Standards

All contributions must pass these checks:

### Formatting

```bash
mix format
mix format --check-formatted  # CI check
```

### Compilation

```bash
mix compile --warnings-as-errors
```

### Static Analysis

```bash
mix dialyzer
```

### Linting

```bash
mix credo --min-priority higher
```

### Combined Check

```bash
mix quality  # Runs all of the above
```

## Commit Message Convention

We use [Conventional Commits](https://www.conventionalcommits.org/) enforced by `git_ops`. All commit messages must follow this format:

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Types

| Type | Description |
|------|-------------|
| `feat` | A new feature |
| `fix` | A bug fix |
| `docs` | Documentation only changes |
| `style` | Changes that don't affect code meaning (formatting) |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `perf` | Performance improvement |
| `test` | Adding or correcting tests |
| `chore` | Changes to build process or auxiliary tools |
| `ci` | CI configuration changes |

### Examples

```bash
# Feature
git commit -m "feat(schema): add new personality trait schema"

# Bug fix
git commit -m "fix(memory): enforce capacity limits correctly"

# Breaking change
git commit -m "feat(api)!: change character map structure"
```

### Validation

The `git_hooks` commit-msg hook will reject non-conforming commits:

```bash
# This will be rejected
git commit -m "updated character schema"

# This will pass
git commit -m "feat(schema): add voice vocabulary field"
```

## Pull Request Process

1. **Create a Feature Branch**
   ```bash
   git checkout -b feat/your-feature-name
   ```

2. **Develop with Tests**
   - Write tests first (TDD encouraged)
   - Run quality checks frequently

3. **Verify Everything Passes**
   ```bash
   mix test
   mix quality
   ```

4. **Update Documentation**
   - Add/update module docs
   - Update README if needed
   - Do **NOT** edit `CHANGELOG.md` (it is auto-generated by git_ops)

5. **Submit Pull Request**
   - Use descriptive title following conventional commits
   - Reference related issues
   - Include test output

### PR Checklist

- [ ] All tests pass (`mix test`)
- [ ] Quality checks pass (`mix quality`)
- [ ] Coverage >= 90% (`mix coveralls`)
- [ ] New tests added for new functionality
- [ ] Documentation updated
- [ ] I have **NOT** edited `CHANGELOG.md` (it is auto-generated by git_ops)
- [ ] Commit messages follow conventional commits

## Architecture Notes

### Characters are Maps

Characters are plain Elixir maps validated by Zoi schemas. This enables:
- Full Access behaviour compatibility
- Easy serialization with Jason
- Pattern matching in function heads

### Immutability

All update operations return new maps:
```elixir
{:ok, updated} = Jido.Character.update(character, %{name: "New Name"})
# `character` is unchanged, `updated` is the new version
```

### Extensions

The package supports extensions for domain-specific needs:
```elixir
defmodule MyApp.Characters.Alice do
  use Jido.Character,
    extensions: [:memory, :goals],
    defaults: %{name: "Alice"}
end
```

## Questions?

- **Documentation**: Check the README and hexdocs
- **Issues**: Open an issue for questions or bug reports
- **Discord**: Join [The Swarm: Elixir AI Collective](https://agentjido.xyz/discord)

## License

By contributing to Jido Character, you agree that your contributions will be licensed under the Apache License 2.0.

---

Thank you for helping make Jido Character better!