Contributing to Probe

Thank you for considering contributing to Probe! This document provides guidelines and instructions to make the contribution process smooth and effective.

Table of Contents

• Code of Conduct
• Development Setup
• Development Workflow
• Pull Request Process
• Testing Guidelines
• Coding Standards
• Documentation
• Release Process

Code of Conduct

By participating in this project, you are expected to uphold our Code of Conduct. Please report unacceptable behavior to the project maintainers.

Development Setup

Prerequisites

• Rust and Cargo (latest stable version)
• Git
• Make (for using the Makefile commands)

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR-USERNAME/probe.git
   cd probe
   

3. Set up the git hooks to ensure code quality:

   make install-hooks
   

4. Add the original repository as a remote to keep your fork updated:

   git remote add upstream https://github.com/probelabs/probe.git
   

Building the Project

To build the project in debug mode:

make build

To run the application:

make run

For a release build:

make run-release

Development Workflow

1. Create a new branch for your feature or bugfix:

   git checkout -b feature/your-feature-name
   

   or

   git checkout -b fix/issue-you-are-fixing
   

2. Make your changes, following the Coding Standards

3. Run tests to ensure your changes don't break existing functionality:

   make test
   

4. Format your code:

   make format
   

5. Run the linter:

   make lint
   

6. Commit your changes using the Git Commit Message Guidelines

7. Push your branch to your fork:

   git push origin feature/your-feature-name
   

8. Create a Pull Request from your fork to the main repository

Pull Request Process

1. Ensure your PR includes a clear description of the changes and the purpose
2. Link any related issues using keywords like "Fixes #123" or "Resolves #456"
3. Make sure all tests pass and there are no linting errors
4. Add tests for new functionality
5. Update documentation as needed
6. Your PR will be reviewed by maintainers who may request changes
7. Once approved, your PR will be merged

Testing Guidelines

Probe uses several types of tests to ensure quality:

Running Tests

• Run all tests:

  make test
  

• Run specific test types:

  make test-unit          # Unit tests
  make test-integration   # Integration tests
  make test-property      # Property-based tests
  make test-cli           # CLI tests
  

Writing Tests

• Unit Tests: Place in the same file as the code being tested, using Rust's #[cfg(test)] module
• Integration Tests: Add to the tests/ directory
• Property Tests: Use the proptest framework for property-based testing
• CLI Tests: Test the command-line interface functionality

Coding Standards

Rust Style Guidelines

• Follow the Rust API Guidelines
• Use rustfmt for consistent formatting (run make format)
• Use clippy to catch common mistakes (run make lint)

Git Commit Message Guidelines

• Use the present tense ("Add feature" not "Added feature")
• Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
• Limit the first line to 72 characters or less
• Reference issues and pull requests after the first line
• Consider using emoji prefixes for better readability:
  • 🎨 :art: when improving code structure/format
  • 🐎 :racehorse: when improving performance
  • 📝 :memo: when writing docs
  • 🐛 :bug: when fixing a bug
  • ✅ :white_check_mark: when adding tests
  • 🔒 :lock: when dealing with security

Documentation

• Update the README.md if you change functionality
• Document all public API items with rustdoc comments
• Include examples in documentation where appropriate
• Generate documentation with:

  make doc
  

Adding Support for New Languages

If you want to add support for a new programming language:

1. Add the appropriate tree-sitter grammar dependency to Cargo.toml
2. Implement the language parser in the src/language directory
3. Update the language detection logic
4. Add tests for the new language support
5. Update the documentation to include the new supported language

Release Process

Releases are managed by the project maintainers. The process involves:

1. Updating the version in Cargo.toml
2. Building release packages for all supported platforms:

   VERSION=vX.Y.Z make release
   

3. Creating a new GitHub release with release notes
4. Publishing the updated package

Questions?

If you have any questions about contributing, feel free to open an issue or contact the project maintainers.

Thank you for contributing to Probe!