Thank you for your interest in contributing to Brat! This document provides guidelines and information for contributors.
- Code of Conduct
- Getting Started
- Development Setup
- How to Contribute
- Pull Request Process
- Coding Standards
- Testing
- Documentation
This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.
- Rust (stable, 1.75+): Install via rustup
- Node.js (20+): For the web UI
- Git: Version 2.30+
- Grite: The substrate for brat - see grite repository
-
Clone the repository
git clone https://github.com/neul-labs/brat.git cd brat -
Build the Rust components
cargo build --release
-
Set up the web UI
cd brat-ui npm install npm run dev -
Run tests
cargo test cd brat-ui && npm run build
Before creating a bug report, please check existing issues to avoid duplicates. When creating a bug report, include:
- A clear, descriptive title
- Steps to reproduce the issue
- Expected behavior vs actual behavior
- Your environment (OS, Rust version, Node version)
- Relevant logs or error messages
Feature suggestions are welcome! Please:
- Check existing issues and discussions first
- Provide a clear use case
- Explain why this feature would be useful to most users
- Consider how it fits with the project's goals
- Find an issue to work on - Look for issues labeled
good first issueorhelp wanted - Comment on the issue - Let others know you're working on it
- Fork and branch - Create a feature branch from
main - Make your changes - Follow the coding standards below
- Test your changes - Ensure all tests pass
- Submit a pull request - Reference the issue in your PR
-
Create a feature branch
git checkout -b feature/your-feature-name
-
Make atomic commits with clear messages:
feat: add convoy status filtering - Add status filter to convoy list endpoint - Update UI to show filter dropdown - Add tests for new functionality -
Keep PRs focused - One feature or fix per PR
-
Update documentation if needed
-
Ensure CI passes - All tests and lints must pass
-
Request review - Tag maintainers for review
We follow Conventional Commits:
feat:- New featuresfix:- Bug fixesdocs:- Documentation changesstyle:- Code style changes (formatting, etc.)refactor:- Code refactoringtest:- Adding or updating testschore:- Maintenance tasks
- Follow the Rust API Guidelines
- Run
cargo fmtbefore committing - Run
cargo clippyand address warnings - Use meaningful variable and function names
- Add doc comments for public APIs
/// Creates a new convoy with the given title.
///
/// # Arguments
///
/// * `title` - The convoy title (must be non-empty)
/// * `body` - Optional description
///
/// # Errors
///
/// Returns an error if the title is empty or if grite operations fail.
pub fn create_convoy(title: &str, body: Option<&str>) -> Result<Convoy> {
// ...
}- Use TypeScript for all new code
- Follow Vue 3 Composition API patterns
- Use
<script setup lang="ts">syntax - Run
npm run buildto check for type errors
- Keep functions small and focused
- Prefer explicit over implicit
- Handle errors gracefully
- Avoid premature optimization
# Run all tests
cargo test
# Run tests for a specific crate
cargo test -p libbrat-engine
# Run with output
cargo test -- --nocapturecd brat-ui
npm run build # Type checking
npm run lint # Linting (if configured)- Write tests for new functionality
- Include edge cases and error conditions
- Use descriptive test names
#[test]
fn create_convoy_with_empty_title_fails() {
let result = create_convoy("", None);
assert!(result.is_err());
}- Update README.md for user-facing changes
- Add doc comments to public Rust APIs
- Update
docs/for architectural changes - Include code examples where helpful
brat/
├── crates/
│ ├── brat/ # Main CLI binary
│ ├── libbrat-engine/ # Core engine logic
│ ├── libbrat-grite/ # Grite integration
│ └── libbrat-ipc/ # IPC protocols
├── brat-ui/ # Vue.js web dashboard
├── docs/ # Architecture documentation
└── scripts/ # Helper scripts
- Open a Discussion for questions
- Check existing Issues for known problems
- Read the Documentation for architecture details
By contributing to Brat, you agree that your contributions will be licensed under the MIT License.