Skip to main content
Thank you for considering contributing to LibXMTP! Community contributions are key to the development and adoption of XMTP.

​
Ways to Contribute

​
Questions

Have a question about building with XMTP? Ask in the XMTP Community Forums.

​
Bug Reports

Report bugs using GitHub Issues. Please include:
  • Clear description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, Rust version, etc.)

​
Feature Requests

Request features using GitHub Issues. Consider:
  • Describing the use case
  • Explaining why existing features don’t address your needs
  • Proposing a potential implementation approach

​
Pull Requests

PRs are encouraged, but consider starting with a feature request to temperature-check first.
If the PR involves a major change to the protocol, the work should be fleshed out as an XMTP Improvement Proposal (XIP) before work begins.

​
Approval Process

After a pull request is submitted, a single approval is required to merge it.

​
AI-Generated Contributions Policy

We do not accept pull requests that are generated entirely or primarily by AI/LLM tools (e.g., GitHub Copilot, ChatGPT, Claude).
This includes:
  • Automated typo fixes or formatting changes
  • Generic code improvements without context
  • Mass automated updates or refactoring
Pull requests that appear to be AI-generated without meaningful human oversight will be closed without review.
To protect project quality and maintain contributor trust, we will restrict access for users who continue to submit AI-generated pull requests.

​
Using AI Tools Responsibly

If you use AI tools to assist your development process, please:
1

Review thoroughly

Thoroughly review and understand all generated code before submitting.
2

Provide context

Include detailed PR descriptions explaining your changes and reasoning.
3

Be prepared to discuss

Be ready to discuss your implementation decisions and how they align with project goals.

​
Code Quality Requirements

Before submitting a PR, ensure your code meets quality standards:

​
Linting

just lint
ALWAYS run just lint before committing Rust changes.
For Node.js bindings changes: 
just node lint

​
Formatting

Format all code before submitting: 
just format
This formats:
  • Rust code
  • Nix files
  • TOML configuration
  • TypeScript (Node.js bindings)
  • Swift (iOS bindings)
  • Kotlin (Android bindings)

​
Testing

Add test coverage for new functionality: 
just test
See the Testing guide for more details.

​
Development Workflow

1

Set up environment

Follow the Development Setup guide to configure your environment.
2

Create a branch

Create a feature branch from main:
git checkout -b feature/your-feature-name
3

Make changes

Implement your changes following the project’s coding standards.
4

Run quality checks

Before committing:
just lint
just test
5

Commit changes

Write clear, descriptive commit messages:
git commit -m "feat: add support for X"
6

Push and create PR

Push your branch and create a pull request on GitHub.

​
Coding Standards

​
Rust Guidelines

  • Follow the official Rust API Guidelines
  • Use rustfmt for consistent formatting (run via just format)
  • Address all clippy warnings (run via just lint-rust)
  • Write documentation for public APIs
  • Add tests for new functionality

​
Test Writing

  • Use #[xmtp_common::test(unwrap_try = true)] instead of #[test]
  • Use rstest for parameterized tests
  • Use the tester! macro for tests requiring wallets
  • Include both unit and integration tests where appropriate
See the Testing guide for details.

​
Dependency Management

When adding dependencies:
  1. Consider the impact on bundle size (especially for WASM)
  2. Ensure licenses are compatible
  3. Regenerate the workspace-hack: 
    nix develop --command cargo hakari generate

​
Architecture Guidelines

LibXMTP follows specific architectural patterns:
  • Generic Client: Client<Context> parameterized by context
  • Builder Pattern: Use ClientBuilder for complex object construction
  • Trait Abstractions: Implement traits (XmtpApi, XmtpDb, InboxOwner) for pluggability
  • Platform-specific code: Use if_native!/if_wasm! macros

​
Documentation

Good documentation helps everyone:
  • Document public APIs with doc comments
  • Include code examples in documentation
  • Update relevant guides when changing behavior
  • Keep the README up to date

​
Getting Help

If you need help with your contribution:
  • Ask questions in the XMTP Community Forums
  • Review the CLAUDE.md file for project context
  • Look at existing PRs for examples
  • Reach out to maintainers via GitHub

​
Code Review Process

When your PR is submitted:
  1. Automated checks will run (linting, tests, etc.)
  2. A maintainer will review your code
  3. You may be asked to make changes
  4. Once approved, your PR will be merged
Be patient and responsive to feedback. Code review is a collaborative process that improves code quality.

​
License

By contributing to LibXMTP, you agree that your contributions will be licensed under the same license as the project.

Build docs developers (and LLMs) love

Get started for freeTalk to us