noentropy/docs/CONTRIBUTING.md

Contributing to NoEntropy

Thank you for considering contributing to NoEntropy! This guide will help you get started with contributing to the project.

Table of Contents

• Code of Conduct
• How Can I Contribute?
• Development Setup
• Pull Request Process
• Coding Standards
• Commit Message Guidelines
• Testing Guidelines
• Documentation Guidelines

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inspiring community for everyone. Please be respectful and constructive in your interactions.

Expected Behavior

• Be respectful and inclusive
• Accept constructive criticism gracefully
• Focus on what's best for the community
• Show empathy towards other community members

Unacceptable Behavior

• Harassment or discriminatory language
• Trolling or insulting comments
• Public or private harassment
• Publishing others' private information

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates.

How to submit a good bug report:

1. Use a clear and descriptive title
2. Describe the exact steps to reproduce the problem
3. Provide specific examples
4. Describe the behavior you observed and what you expected
5. Include system information:
   • OS and version
   • Rust version
   • NoEntropy version

Bug report template:

**Description**
A clear description of the bug.

**Steps to Reproduce**
1. Run command '...'
2. See error '...'

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

**Actual Behavior**
What actually happened.

**System Information**
- OS: [e.g., Ubuntu 22.04]
- Rust version: [e.g., 1.75.0]
- NoEntropy version: [e.g., 1.0.0]

**Additional Context**
Any other relevant information.

Suggesting Enhancements

Enhancement suggestions are welcome! Please provide:

1. Clear use case: Explain why this enhancement would be useful
2. Detailed description: Describe how it should work
3. Examples: Provide examples of how it would be used
4. Alternatives considered: Mention alternative solutions you've considered

Enhancement template:

**Feature Description**
A clear description of the feature.

**Use Case**
Why this feature would be useful.

**Proposed Solution**
How you think it should work.

**Alternatives Considered**
Other solutions you've thought about.

**Additional Context**
Any other relevant information.

Contributing Code

We love code contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

See Development Setup below for details.

Improving Documentation

Documentation improvements are highly valued:

• Fix typos or unclear explanations
• Add examples or clarifications
• Improve code comments
• Write tutorials or guides

Helping Others

• Answer questions in GitHub Issues
• Participate in discussions
• Help review pull requests
• Share your use cases and experiences

Development Setup

Prerequisites

• Rust 2024 Edition or later
• Git for version control
• Google Gemini API Key for testing (get one at https://ai.google.dev/)

Setup Steps

1. Fork and clone the repository:

   git clone https://github.com/YOUR_USERNAME/noentropy.git
   cd noentropy
   

2. Add upstream remote:

   git remote add upstream https://github.com/glitchySid/noentropy.git
   

3. Build the project:

   cargo build
   

4. Run tests:

   cargo test
   

5. Set up configuration (for testing):

   cp config.example.toml ~/.config/noentropy/config.toml
   # Edit config.toml with your API key and test folder
   

6. Verify installation:

   cargo run -- --dry-run
   

Keeping Your Fork Updated

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Pull Request Process

Before Submitting

1. Ensure tests pass:

   cargo test
   

2. Run code formatter:

   cargo fmt
   

3. Run linter:

   cargo clippy
   

4. Test manually with various scenarios

5. Update documentation if needed

Creating a Pull Request

1. Create a feature branch:

   git checkout -b feature/your-feature-name
   

2. Make your changes and commit:

   git add .
   git commit -m "Add feature: description"
   

3. Push to your fork:

   git push origin feature/your-feature-name
   

4. Open a pull request on GitHub

5. Fill out the PR template with:

   • Description of changes
   • Related issue number (if applicable)
   • Testing performed
   • Screenshots (if UI changes)

PR Review Process

1. Automated checks will run (tests, linting, formatting)
2. Maintainers will review your code
3. Address feedback by making additional commits
4. Once approved, your PR will be merged

PR Guidelines

• Keep PRs focused: One feature or fix per PR
• Write clear descriptions: Explain what and why
• Reference issues: Use "Fixes #123" to link issues
• Be responsive: Respond to review feedback promptly
• Be patient: Reviews may take time

Coding Standards

Rust Style Guide

Follow the official Rust Style Guide:

• Use cargo fmt to format code
• Use cargo clippy to catch common mistakes
• Follow Rust naming conventions:
  • snake_case for functions and variables
  • PascalCase for types and traits
  • SCREAMING_SNAKE_CASE for constants

Code Organization

• Keep functions focused and small
• Group related functionality in modules
• Use meaningful variable and function names
• Avoid deep nesting (prefer early returns)

Error Handling

• Use Result types for fallible operations
• Provide meaningful error messages
• Don't panic in library code
• Use ? operator for error propagation

Comments and Documentation

• Add doc comments (///) for public APIs
• Explain "why" not "what" in comments
• Keep comments up-to-date with code changes
• Use examples in doc comments when helpful

Example

/// Calculates the destination path for a file based on its category.
///
/// # Arguments
///
/// * `file_path` - The original file path
/// * `category` - The category to organize into
/// * `subfolder` - Optional subfolder within category
///
/// # Examples
///
/// ```
/// let dest = calculate_destination("/downloads/file.txt", "Documents", Some("Work"));
/// assert_eq!(dest, "/downloads/Documents/Work/file.txt");
/// ```
///
/// # Errors
///
/// Returns an error if the path cannot be constructed.
pub fn calculate_destination(
    file_path: &Path,
    category: &str,
    subfolder: Option<&str>
) -> Result<PathBuf, Error> {
    // Implementation
}

Commit Message Guidelines

Format

<type>(<scope>): <subject>

<body>

<footer>

Type

• 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

Examples

Good commit messages:

feat(cli): add recursive flag for subdirectory scanning

Adds --recursive flag to scan and organize files in subdirectories.
This is useful when downloads are already partially organized.

Fixes #42

fix(cache): prevent cache corruption on interrupted writes

Use atomic writes to ensure cache file is not corrupted if
process is interrupted during save operation.

docs: update configuration guide with new examples

Add examples for different user types (students, professionals).
Clarify custom category usage.

Bad commit messages:

fix stuff

WIP

more changes

Tips

• Use present tense ("add feature" not "added feature")
• Be specific and descriptive
• Reference issues and PRs when relevant
• Keep subject line under 72 characters
• Separate subject from body with blank line

Testing Guidelines

Writing Tests

• Write tests for new functionality
• Test both success and error cases
• Use descriptive test names
• Keep tests focused and independent

Test Structure

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

    #[test]
    fn test_parse_valid_config() {
        // Arrange
        let config_str = r#"
            api_key = "test_key"
            download_folder = "/tmp/test"
        "#;

        // Act
        let result = parse_config(config_str);

        // Assert
        assert!(result.is_ok());
        let config = result.unwrap();
        assert_eq!(config.api_key, "test_key");
        assert_eq!(config.download_folder, "/tmp/test");
    }

    #[test]
    fn test_parse_invalid_config() {
        let config_str = "invalid toml";
        let result = parse_config(config_str);
        assert!(result.is_err());
    }
}

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run with output
cargo test -- --nocapture

# Run tests in specific module
cargo test module_name::

Documentation Guidelines

Code Documentation

• Document all public APIs
• Include examples in doc comments
• Explain parameters and return values
• Document errors that can occur

User Documentation

When updating user-facing docs:

• Keep language clear and simple
• Provide examples
• Include screenshots for UI changes
• Update all relevant docs

Documentation Files

• README.md: Project overview and quick start
• docs/INSTALLATION.md: Installation instructions
• docs/CONFIGURATION.md: Configuration guide
• docs/USAGE.md: Usage examples and options
• docs/HOW_IT_WORKS.md: Architecture and internals
• docs/TROUBLESHOOTING.md: Common issues and solutions
• docs/DEVELOPMENT.md: Development guide
• docs/CONTRIBUTING.md: This file

Questions?

• Check existing documentation
• Search GitHub Issues
• Ask in GitHub Discussions
• Contact maintainers

Recognition

Contributors will be recognized in:

• GitHub contributors list
• Release notes (for significant contributions)
• Project documentation (for major features)

License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to NoEntropy!

Back to Main README | Development Guide