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
• Development Setup
• Testing Requirements
• Code Quality Standards
• Commit Message Convention
• Pull Request Process
• 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

# 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 to enforce commit message conventions:

mix git_hooks.install

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

Testing Requirements

# 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

mix format
mix format --check-formatted  # CI check

Compilation

mix compile --warnings-as-errors

Static Analysis

mix dialyzer

Linting

mix credo --min-priority higher

Combined Check

mix quality  # Runs all of the above

Commit Message Convention

We use Conventional Commits enforced by git_ops. All commit messages must follow this format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

Examples

# 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:

# 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

   git checkout -b feat/your-feature-name
   

2. Develop with Tests

   • Write tests first (TDD encouraged)
   • Run quality checks frequently

3. Verify Everything Passes

   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:

{: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:

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

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!