Contributing to Smart Tree 🌳✨

January 22, 2026 · View on GitHub

Welcome, brave code warrior! You've stumbled upon our contributing guide, which means you're either:

  1. A developer with brilliant ideas (Aye loves you already!)
  2. Someone who found a bug (Hue is already investigating!)
  3. Trisha from Accounting who got lost looking for the expense reports (wrong repo, Trish!)

Whatever brought you here, we're thrilled to have you! 🎉

🚀 Quick Start for Contributors

The Three Commandments of Smart Tree

  1. Fast is better than slow - If it takes longer than brewing coffee, it's too slow
  2. Pretty is better than ugly - Code should sparkle like Trisha's spreadsheets
  3. Simple is better than complex - If Hue can't understand it, it needs more comments

Setting Up Your Development Environment

  1. Clone the repo (you probably already did this, but Trisha insists we mention it):

    git clone https://github.com/8b-is/smart-tree.git
cd smart-tree

  2. Build the project (grab a coffee, this might take a minute):

    cargo build

  3. Run the tests (make sure you didn't break anything that Aye worked hard on):

    cargo test

  4. Try it out:

    cargo run --bin st -- --help

  5. Install locally (recommended for development):

    ./scripts/build-and-install.sh

🔧 Development Tips

Version Command Hanging? If st --version hangs after rebuilding, your shell has cached the old binary location. Solutions:

Quick fix:

hash -r && st --version

Automatic solution: Use our build script:

./scripts/build-and-install.sh

Add to your shell: Source our helper functions for convenient development:

# Add to ~/.zshrc or ~/.bashrc
source /path/to/smart-tree/scripts/shell-functions.sh

# Then use these commands:
st-rebuild   # Build and install with cache clearing
st-test      # Test local build without installing  
st-refresh   # Clear cache and test version
st-versions  # Check both installed and local versions

🐛 Found a Bug?

Don't panic! Bugs happen to the best of us. Even Aye occasionally writes code that doesn't work on the first try (shocking, we know).

  1. Check if it's already reported - Someone else might have beaten you to it
  2. Use our bug report template - It's funnier than your average template
  3. Be descriptive - "It doesn't work" is about as helpful as Trisha's diet tips
  4. Include your environment - OS, Rust version, whether you're using it during a full moon, etc.

💡 Have a Feature Idea?

Brilliant! We love new ideas almost as much as Hue loves optimizing directory traversal algorithms.

  1. Use our feature request template - It's got jokes AND structure
  2. Explain the why - Why would this make Smart Tree even smarter?
  3. Consider alternatives - Show us you've thought it through
  4. Be patient - Good features take time, like aging cheese or Trisha's quarterly reports

🔧 Development Guidelines

Code Style

  • Rust formatting: Use cargo fmt - consistent code makes Aye happy
  • Comments: Write them like you're explaining to future you at 3 AM
  • Error handling: Use Result<T> and anyhow - panics are for parties, not production
  • Tests: Write them! Even Hue's perfect code needs tests

Commit Messages

Follow the format: type: short description

Types we recognize:

  • feat: New feature (Aye gets excited)
  • fix: Bug fix (Hue breathes a sigh of relief)
  • docs: Documentation (Trisha actually reads these)
  • style: Code style changes (make it pretty!)
  • refactor: Code improvements (Hue's favorite)
  • test: Adding tests (responsible development!)
  • chore: Maintenance tasks (someone has to do it)

Example: feat: add quantum compression for directory trees

Pull Request Process

  1. Fork the repo (it's like borrowing, but for code)
  2. Create a branch with a descriptive name: feature/awesome-new-thing
  3. Make your changes (the fun part!)
  4. Write tests (the responsible part)
  5. Update documentation if needed (Trisha will thank you)
  6. Submit a PR with a clear description
  7. Be patient - we'll review it faster than Trisha processes expense reports

What Makes a Good PR?

  • Clear description - What does it do? Why does it matter?
  • Tests included - Show us it works!
  • Documentation updated - If you added features, document them
  • Single responsibility - One thing at a time, please
  • Backwards compatible - Don't break existing users' workflows

🎯 Areas Where We Need Help

  • Performance optimizations (Hue's specialty, but all hands welcome!)
  • New output formats (creativity encouraged!)
  • Documentation improvements (Trisha's domain, but she welcomes help)
  • Platform-specific testing (Windows, Linux, macOS, BSD, Commodore 64...)
  • Integration guides (AI tools, editors, CI/CD systems)

📚 Architecture Overview

Smart Tree is structured like a well-organized filing cabinet (the kind Trisha dreams about):

  • Scanner: The explorer (finds files, respects .gitignore, doesn't judge your file naming)
  • Formatters: The artists (turn raw data into beautiful output)
  • Config: The organizer (handles settings and preferences)
  • MCP: The diplomat (talks to AI tools)

🧪 Testing Philosophy

We believe in testing like Trisha believes in properly organized spreadsheets:

  • Unit tests for individual functions
  • Integration tests for formatters and scanners
  • Performance tests for large directories
  • Real-world tests on actual codebases

Run tests with:

cargo test
cargo test --release  # For performance tests

📖 Documentation

Good documentation is like a good joke - if you have to explain it, it's not good enough. But here are our standards:

  • README: Keep it current (first impressions matter!)
  • Code comments: Explain the "why", not just the "what"
  • Examples: Show don't tell
  • Changelog: Document breaking changes (users will thank you)

🎉 Recognition

Contributors get:

  • Eternal gratitude from Aye, Hue, and Trisha
  • Mention in the changelog (internet fame!)
  • Warm fuzzy feelings from helping the community
  • The satisfaction of making directory trees more beautiful

📞 Getting Help

Stuck? Don't suffer in silence!

  • GitHub Issues: For bugs and features
  • GitHub Discussions: For questions and ideas
  • Email: For sensitive matters (or if you want to send Trisha cookies)

🙏 Thank You!

Every contribution, from typo fixes to major features, makes Smart Tree better. You're the reason we can keep making directory visualization awesome.

Remember: We're building something that developers use every day. Your code could be the difference between someone having a good day or spending an hour trying to understand a directory structure.

Now go forth and make some beautiful code! 🚀

"Contributing to open source is like tending a garden - with enough care and attention, beautiful things grow!" - Trisha from Accounting (who somehow became philosophical)

Happy coding! 🌳✨