Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
187 lines (120 loc) · 7.89 KB

CONTRIBUTING.md

File metadata and controls

187 lines (120 loc) · 7.89 KB
Raw

Contributing to MUXI

Thank you for your interest in contributing to MUXI!

Note

These guidelines apply to all MUXI repositories including the server, runtime, CLI, SDKs, and documentation.

Quick Links

Find Something to Work On

Looking for ways to contribute? Check issues with these labels:

Want to take on an issue? Leave a comment and a maintainer may assign it to you.

The Basics

PRs Target develop

All pull requests must target the develop branch, not main. We use a three-branch workflow:

develop → rc → main

See GIT-WORKFLOW.md for details.

Issue First

Before opening a PR, an issue must exist and you must be assigned to it (except for minor fixes). This ensures:

  • The change aligns with project goals
  • No duplicate work
  • You get guidance before implementation

How to start:

  1. Browse existing issues or create a new one
  2. Comment asking to be assigned
  3. Wait for assignment
  4. Then start coding

What's a "Minor Fix"?

These don't need an issue:

  • ✅ Typo fixes in docs, comments, or error messages
  • ✅ Broken link corrections
  • ✅ Formatting fixes (indentation, whitespace)
  • ✅ Small grammar corrections

These do need an issue:

  • ❌ Any code logic changes
  • ❌ New dependencies
  • ❌ API changes
  • ❌ UI/UX changes
  • ❌ Performance optimizations
  • ❌ Security-related changes

When in doubt, create an issue.

AI-Assisted Development

We welcome AI-assisted contributions that meet our quality standards. MUXI is built with significant AI assistance.

Quick rules:

  • ✅ Test your changes locally
  • ✅ Understand and be able to explain your code
  • ❌ No drive-by AI PRs (work on accepted issues only)
  • ❌ No committing agent dotfiles (.claude/, .factory/, etc.)

Warning

Low-effort AI-generated contributions will be closed and may result in a ban.

Read the full policy: AI-POLICY.md

What We Accept

  • 🐛 Bug fixes - Fix existing issues
  • ✨ Features - New functionality (discuss first)
  • 📝 Documentation - Improve guides and docs
  • 🧪 Tests - Improve coverage
  • 🔧 DX improvements - Better tooling and workflows

What We Don't Accept

  • PRs without associated issues (except minor fixes)
  • Code that hasn't been tested locally
  • Changes that break existing functionality
  • Code that doesn't follow our style guidelines
  • Large refactoring without prior discussion
  • Manual version bumps - CI/CD handles versioning automatically

Pull Request Expectations

  • Keep PRs small and focused – easier to review, faster to merge
  • Link relevant issue(s) in the description
  • Explain the problem and why your change fixes it
  • Before adding new functions, ensure similar behavior doesn't already exist elsewhere in the codebase
  • Test locally before submitting

Feature Requests

For net-new functionality, start with a design conversation. Open an issue describing:

  1. The problem you're trying to solve
  2. Your proposed approach (optional)
  3. Why it belongs in MUXI

Wait for maintainer approval before opening a feature PR. This helps ensure alignment with project direction and avoids wasted effort.

Branch Naming

feature/descriptive-name
fix/bug-description
docs/what-changed
refactor/what-improved
hotfix/critical-issue

Commit Messages

Follow Conventional Commits:

feat: add memory persistence option
fix: resolve session timeout bug
docs: update API reference
chore: update dependencies
test: add integration tests for chat endpoint
  • Use present tense ("Add feature" not "Added feature")
  • Keep first line under 72 characters
  • Reference issues when applicable: Fix timeout bug (#123)

Code Review Process

  1. Automated checks must pass (lint, tests, types)
  2. Manual review by maintainers
  3. Address feedback promptly
  4. Squash commits if requested

Security

Found a vulnerability? Do not open a public issue.

Email security@muxi.org instead.

Getting Help

License

By contributing, you agree to license your contributions under the same license as the project. Please review our Contributor License Agreement.

Quality over quantity. We prefer well-tested, thoughtful contributions over quick fixes that might introduce issues.