Contributing Guide

How to contribute to Rode and help make it better

Welcome! We’re excited that you’re interested in contributing to Rode. This guide will help you get started.

Getting Started

1. Fork the repository

   Fork kashsuks/rode to your GitHub account

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/rode
   cd rode
   
3. Set up development environment

   Follow the Building from Source guide to set up your environment

4. Create a feature branch

   git checkout -b feature/your-feature-name
   

Development Setup

Prerequisites

Ensure you have:

Rust Toolchain

Rust 2021 edition or later

rustup update stable

Code Editor

Any editor with Rust support

Recommended: VS Code with rust-analyzer

Git

Version control system

git --version

Cargo Tools

Helpful cargo extensions

cargo install cargo-watch
cargo install cargo-edit

Running in Development Mode

Use cargo watch for automatic rebuilds during development:

cargo watch -x run

This will automatically recompile and restart Rode whenever you save changes.

Code Style

Formatting

Rode uses standard Rust formatting. Before committing:

cargo fmt

Set up your editor to run cargo fmt on save for automatic formatting.

Linting

Run Clippy to catch common mistakes and improve code quality:

cargo clippy -- -D warnings

This treats all warnings as errors to maintain high code quality.

Code Organization

Follow these conventions:

Module Structure

• Keep modules focused on a single responsibility
• Use mod.rs for module organization
• Export public APIs through module re-exports

Example:

// src/autocomplete/mod.rs
pub mod context;
pub mod engine;
pub mod language;
pub mod scoring;
pub mod types;

Naming Conventions

• Use snake_case for functions, variables, modules
• Use PascalCase for types, structs, enums
• Use SCREAMING_SNAKE_CASE for constants

const SIDEBAR_DEFAULT_WIDTH: f32 = 180.0;

pub struct FileTree {
    pub root: PathBuf,
}

fn scan_directory(path: &Path) -> Vec<FileEntry> {
    // ...
}

Documentation

Add doc comments for public APIs:

/// Scan a directory and return a list of FileEntry.
/// 
/// This function recursively scans the given path and builds
/// a vector of file entries, skipping ignored directories.
fn scan_directory(path: &Path) -> Vec<FileEntry> {
    // ...
}

Error Handling

• Use Result<T, E> for operations that can fail
• Avoid .unwrap() in production code
• Use .unwrap_or_else() or match for graceful handling

// Good
let content = std::fs::read_to_string(&path)
    .unwrap_or_else(|_| String::from("Could not read file"));

// Avoid
let content = std::fs::read_to_string(&path).unwrap();

Making Changes

Understanding the Codebase

Before making changes, familiarize yourself with:

Architecture

Read the architecture documentation

Message Flow

Understand Iced’s message-driven architecture in src/app.rs

Module Layout

Browse the module organization in src/

Dependencies

Check Cargo.toml for the libraries Rode uses

Types of Contributions

Bug Fixes

Fixing Bugs

1. Identify the issue

   • Reproduce the bug consistently
   • Check existing issues on GitHub
   • Create an issue if one doesn’t exist
2. Locate the code

   • Use the architecture guide to find relevant modules
   • Use cargo clippy to identify potential issues
   • Add debug logging if needed
3. Fix and test

   • Make minimal changes to fix the issue
   • Test thoroughly in both debug and release builds
   • Ensure no regressions in other features
4. Document the fix

   • Add comments explaining non-obvious fixes
   • Update documentation if behavior changes
   • Reference the issue in your commit message

New Features

Adding Features

1. Discuss first

   Open an issue to discuss the feature before implementing:

   • Describe the use case
   • Explain the proposed solution
   • Get feedback from maintainers
2. Design the feature

   • Determine which modules will be affected
   • Design the message flow for user interactions
   • Consider state management needs
3. Implement incrementally

   • Start with core functionality
   • Add UI components
   • Integrate with existing features
   • Test at each stage
4. Add keyboard shortcuts

   If applicable, add shortcuts in app.rs:990 subscription handler

Example: Adding a new command

src/message.rs

// Add message variant
pub enum Message {
    // ...
    MyNewCommand,
}

UI Improvements

Improving UI/UX

UI changes should:

Maintain consistency with existing design

Work with all built-in themes

Be responsive to window resizing

Follow Iced widget patterns

Key files for UI work:

• src/ui/styles.rs - Widget styling functions
• src/ui/editor.rs - Editor widget creation
• src/ui/sidebar.rs - Sidebar rendering
• src/theme.rs - Color themes and constants
• src/app.rs - View composition in view() method

Documentation

Documentation Contributions

Documentation improvements are always welcome:

Code Comments

Add explanatory comments to complex logic

Doc Comments

Write rustdoc comments for public APIs

README Updates

Improve the main README.md

Examples

Add usage examples for features

When updating documentation, make sure examples are tested and accurate.

Testing

Running Tests

Rode includes tests in the tests/ directory:

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run with output
cargo test -- --nocapture

Writing Tests

When adding new features, include tests:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_file_tree_toggle() {
        let mut tree = FileTree::new(PathBuf::from("/test"));
        let path = PathBuf::from("/test/folder");
        
        assert!(!tree.is_expanded(&path));
        tree.toggle_folder(&path);
        assert!(tree.is_expanded(&path));
    }
}

Manual Testing

Test your changes manually:

Commit Guidelines

Commit Messages

Use clear, descriptive commit messages:

# Good
git commit -m "Fix file tree not refreshing after folder delete"
git commit -m "Add fuzzy matching to command palette"
git commit -m "Update theme colors for better contrast"

# Avoid
git commit -m "fix bug"
git commit -m "updates"
git commit -m "wip"

Commit Message Format

Follow this structure:

<type>: <description>

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Example:

feat: Add markdown preview support

Implement markdown preview using Iced's markdown widget.
Previews open in a new tab when Cmd+Shift+V is pressed.

Closes #42

Commit Best Practices

Keep commits focused

Each commit should address one logical change:

✅ Good: Separate commits for different changes

git commit -m "Add fuzzy finder module"
git commit -m "Integrate fuzzy finder with UI"
git commit -m "Add keyboard shortcuts for fuzzy finder"

❌ Avoid: Multiple unrelated changes in one commit

git commit -m "Add fuzzy finder and fix sidebar bug and update README"

Write meaningful messages

Explain why the change was made, not just what changed:

✅ Good:

git commit -m "Fix sidebar width not persisting across sessions

The sidebar width was being reset on startup because preferences
were loaded after the default state was initialized. Load preferences
first to ensure the saved width is applied."

❌ Avoid:

git commit -m "Change initialization order"

Reference issues

Link commits to related issues:

git commit -m "Fix memory leak in file watcher

The file watcher was not properly cleaning up resources when
switching folders, causing memory usage to grow over time.

Fixes #123"

Pull Request Process

Before Submitting

Creating a Pull Request

1. Push your branch

   git push origin feature/your-feature-name
   
2. Open a PR on GitHub

   Go to the Rode repository and click “New Pull Request”

3. Fill out the template

   Provide:

   • Description: What does this PR do?
   • Motivation: Why is this change needed?
   • Testing: How did you test this?
   • Screenshots: For UI changes
   • Related Issues: Link to issues this PR addresses
4. Wait for review

   Maintainers will review your PR and provide feedback

PR Template Example

## Description
Adds fuzzy file finding with Cmd+P keyboard shortcut.

## Motivation
Users need a faster way to navigate large projects without
manually browsing the file tree.

## Changes
- Added fuzzy_finder module with file indexing
- Integrated fuzzy finder overlay in main view
- Added Cmd+P keyboard shortcut
- Added file preview when navigating results

## Testing
- [x] Tested with small projects (<100 files)
- [x] Tested with large projects (>1000 files)
- [x] Tested fuzzy matching algorithm accuracy
- [x] Tested keyboard navigation
- [x] Tested file preview loading

## Screenshots
[Screenshot of fuzzy finder overlay]

## Related Issues
Closes #45

After Submission

Respond to feedback

• Address review comments promptly
• Ask questions if feedback is unclear
• Push additional commits to the same branch
• Be open to suggestions and alternative approaches

Keep your branch updated

If the main branch changes while your PR is open:

git checkout main
git pull upstream main
git checkout feature/your-feature
git rebase main
git push --force-with-lease

Be patient

Rode is maintained by a solo developer with limited time.

Reviews may take time. Don’t be discouraged if you don’t get immediate feedback.

Code Review

What Reviewers Look For

Correctness

Does the code work as intended? Are there edge cases?

Code Quality

Is the code clean, readable, and idiomatic Rust?

Performance

Are there performance implications? Can it be optimized?

Maintainability

Is the code easy to understand and modify in the future?

Addressing Review Comments

When reviewers request changes:

1. Understand the feedback

   Read the comment carefully. Ask for clarification if needed.

2. Make the changes

   Update your code based on the feedback.

3. Commit and push

   git add .
   git commit -m "Address review feedback: improve error handling"
   git push
   
4. Reply to comments

   Let reviewers know you’ve addressed their feedback or explain why you took a different approach.

Community Guidelines

Be Respectful

Be kind and constructive in discussions

Welcome newcomers and help them get started

Accept that there may be different valid approaches

Focus on the code, not the person

Communication

GitHub Issues

Use issues for:

• Bug reports
• Feature requests
• Questions about the codebase
• Discussion of proposed changes

Pull Requests

Use PRs for:

• Code contributions
• Documentation improvements
• Discussion of specific implementations

Development Tips

Debugging

Use Rust’s built-in debugging:

// Add debug output
dbg!(&variable);

// Print to console
eprintln!("Debug: {:?}", value);

// Use debugger
// Set breakpoints in your IDE/debugger

Performance Profiling

Profile your changes if they affect performance:

# Build with debug info
cargo build --release --profile release-with-debug

# Use a profiler (e.g., cargo-flamegraph)
cargo install flamegraph
cargo flamegraph

Understanding Iced

Rode uses the Iced GUI framework. Helpful resources:

• Iced documentation
• Iced examples
• Iced book

Incremental Development

Work in small, testable increments:

1. Write the minimal code to test your idea
2. Test it works
3. Refactor and improve
4. Add error handling
5. Add documentation
6. Test edge cases

Getting Help

GitHub Issues

Ask questions by opening an issue

Architecture Docs

Review the architecture documentation

Source Code

Read the well-commented source code

Rust Docs

Check the official Rust documentation

Recognition

All contributors are recognized in:

• The GitHub contributors list
• Release notes for significant contributions
• The project README

Your contributions make Rode better for everyone. Thank you for taking the time to contribute!

License

By contributing to Rode, you agree that your contributions will be licensed under the GNU General Public License v3.0.

Next Steps

Architecture

Deep dive into Rode’s architecture

Building

Set up your development environment