Contributing to SledoView

We love your input! We want to make contributing to SledoView as easy and transparent as possible, whether it's:

• Reporting a bug
• Discussing the current state of the code
• Submitting a fix
• Proposing new features
• Becoming a maintainer

Development Process

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.

Pull Requests

Pull requests are the best way to propose changes to the codebase. We actively welcome your pull requests:

1. Fork the repo and create your branch from main.
2. Add tests if you've added code that should be tested.
3. Ensure the test suite passes by running cargo test.
4. Ensure your code is formatted by running cargo fmt.
5. Ensure your code passes linting by running cargo clippy.
6. Update documentation if you've changed APIs.
7. Issue that pull request!

Development Setup

Prerequisites

• Rust 1.70+ (2021 edition)
• Git

Setting Up the Development Environment

1. Clone the repository:

   git clone https://github.com/yourusername/sledoview.git
   cd sledoview

2. Build the project:

   cargo build

3. Run tests:

   cargo test

4. Create a test database (optional):

   cargo run --example create_test_db

5. Run the application:

   cargo run -- example_db

Code Style

We follow standard Rust conventions:

• Formatting: Use cargo fmt to format your code
• Linting: Ensure cargo clippy passes without warnings
• Naming: Follow Rust naming conventions (snake_case for functions/variables, PascalCase for types)
• Documentation: Add doc comments for public APIs
• Error Handling: Use Result types and proper error handling

Testing Guidelines

• Write tests for all new functionality
• Integration tests go in the tests/ directory
• Unit tests go in the same file as the code they test, in a #[cfg(test)] mod tests` block
• Test coverage: Aim for high test coverage of new code
• Test data: Use the helper functions in tests/common/ for creating test databases

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run tests with output
cargo test -- --nocapture

# Run tests in release mode
cargo test --release

Documentation

• API documentation: Use doc comments (///) for public APIs
• README: Update if you change functionality
• CHANGELOG: Add entries for notable changes
• Examples: Add examples for new features

Commit Messages

We prefer clear, descriptive commit messages:

• Use present tense ("Add feature" not "Added feature")
• Use imperative mood ("Move cursor to..." not "Moves cursor to...")
• Limit the first line to 72 characters or less
• Reference issues and pull requests liberally after the first line

Examples:

Add regex support for value searching

- Implement search regex command
- Add comprehensive tests for regex patterns
- Update documentation with regex examples

Fixes #123

Bug Reports

We use GitHub issues to track bugs. Report a bug by opening a new issue.

Great Bug Reports tend to have:

• A quick summary and/or background
• Steps to reproduce
  • Be specific!
  • Give sample code if you can
• What you expected would happen
• What actually happens
• Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)

Bug Report Template

**Summary**: Brief description of the bug

**Environment**:
- OS: [e.g., Windows 10, macOS 12, Ubuntu 20.04]
- Rust version: [e.g., 1.70.0]
- SledoView version: [e.g., 0.1.0]

**Steps to Reproduce**:
1. Run command: `sledoview /path/to/db`
2. Type command: `list *`
3. See error

**Expected Behavior**: 
What you expected to happen

**Actual Behavior**: 
What actually happened

**Additional Context**:
Add any other context about the problem here

Feature Requests

We welcome feature requests! Please provide:

• Use case: Why would this feature be useful?
• Description: What should the feature do?
• Examples: How would you use it?
• Alternatives: Are there workarounds?

Security Issues

If you discover a security vulnerability, please send an email to [[email protected]] instead of using the public issue tracker.

Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code:

• Be respectful and inclusive
• Be patient with newcomers
• Be constructive in feedback
• Focus on the code, not the person

Development Guidelines

Performance

• Benchmark critical paths when making performance changes
• Profile before optimizing - don't guess where bottlenecks are
• Consider memory usage especially when dealing with large databases
• Test with realistic data sizes

Error Handling

• Use appropriate error types from the error module
• Provide helpful error messages that guide users toward solutions
• Handle all error cases - avoid unwrap() in library code
• Test error conditions - ensure error paths are covered

Database Safety

• Read and write operations - Tool supports both read-only browsing and safe write operations
• Transactional safety - All write operations are atomic and properly handled
• Key validation - Comprehensive validation before any write operations
• Backup recommendations - Users should backup databases before extensive modifications
• Proper database locking - Ensure we don't interfere with other processes
• Validate input - Check database format and permissions before accessing
• Handle corruption gracefully - Provide helpful error messages

Platform Compatibility

• Test on multiple platforms when possible
• Use cross-platform dependencies
• Avoid platform-specific code unless necessary
• Document platform-specific behavior

Getting Help

• Documentation: Check the README and inline documentation
• Issues: Search existing issues before creating new ones
• Discussions: Use GitHub Discussions for questions and ideas

Recognition

Contributors will be:

• Listed in the project's contributors
• Mentioned in release notes for significant contributions
• Thanked in the project README

Thank you for contributing to SledoView! 🎉