Contributing to RemoveSamples-NZBGet

Thank you for your interest in contributing to RemoveSamples! This guide will help you get started with development, testing, and submitting contributions.

🚀 Quick Start for Contributors

Prerequisites

• Python 3.8+ installed
• Git for version control
• NZBGet 14.0+ for testing (optional but recommended)
• Basic understanding of NZBGet extensions

Development Setup

# Clone the repository
git clone https://github.com/Anunnaki-Astronaut/RemoveSamples-NZBGet.git
cd RemoveSamples-NZBGet

# Create a development branch
git checkout -b feature/your-feature-name

# Install development dependencies (optional)
pip install prospector pytest

📋 Ways to Contribute

🐛 Bug Reports

Before reporting a bug:

• Check existing Issues
• Test with debug mode enabled
• Gather system information

Good bug reports include:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• System environment (OS, Python version, NZBGet version)
• Debug logs (if applicable)
• Sample file names that trigger the issue

💡 Feature Requests

Before requesting a feature:

• Check existing Issues and Discussions
• Consider if it fits the project scope
• Think about implementation complexity

Good feature requests include:

• Clear use case description
• Expected behavior
• Why existing functionality doesn't meet the need
• Willingness to help implement (if possible)

📖 Documentation Improvements

Documentation contributions are highly valued:

• Fix typos or grammar errors
• Improve clarity of explanations
• Add missing documentation
• Update outdated information
• Translate documentation (future)

🔧 Code Contributions

Code contributions should:

• Follow the existing code style
• Include appropriate tests
• Update documentation if needed
• Pass all existing tests

🏗️ Development Guidelines

Code Style

Python Style Guide:

• Follow PEP 8 style guidelines
• Use meaningful variable and function names
• Add docstrings to functions and classes
• Keep functions focused and small
• Use type hints where appropriate

Example code style:

def should_remove_file(self, file_path: str, file_name: str) -> bool:
    """
    Determine if a file should be removed based on patterns and size.
    
    Args:
        file_path: Full path to the file
        file_name: Name of the file
        
    Returns:
        True if file should be removed, False otherwise
    """
    if self._matches_sample_pattern(file_name):
        return True
        
    if self._is_below_size_threshold(file_path):
        return True
        
    return False

File Structure

RemoveSamples-NZBGet/
├── main.py              # Main extension script
├── manifest.json        # Extension manifest
├── tests.py            # Unit tests
├── README.md           # Repository documentation
├── LICENSE             # License file
└── .github/            # GitHub workflows
    └── workflows/
        ├── tests.yml       # Test automation
        ├── prospector.yml  # Code quality
        └── manifest.yml    # Manifest validation

Testing Requirements

All code changes must include tests:

• Unit tests for new functions
• Integration tests for new features
• Regression tests for bug fixes
• Edge case testing

Running tests:

# Run all tests
python -m unittest tests.py -v

# Run specific test
python -m unittest tests.TestRemoveSamples.test_pattern_matching -v

# Run with coverage (if installed)
python -m coverage run -m unittest tests.py
python -m coverage report

Code Quality

Before submitting code:

# Check code quality with Prospector
prospector main.py

# Fix any issues found
# Aim for a clean report

Quality standards:

• No critical or high-severity issues
• Minimal low-severity warnings
• Consistent code style
• Appropriate complexity levels

🔄 Contribution Workflow

1. Fork and Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR-USERNAME/RemoveSamples-NZBGet.git
cd RemoveSamples-NZBGet

# Add upstream remote
git remote add upstream https://github.com/Anunnaki-Astronaut/RemoveSamples-NZBGet.git

2. Create Feature Branch

# Create and switch to feature branch
git checkout -b feature/your-feature-name

# Use descriptive branch names:
# feature/add-custom-patterns
# bugfix/fix-permission-error
# docs/improve-installation-guide

3. Make Changes

• Write your code following the style guidelines
• Add tests for any new functionality
• Update documentation if needed
• Test thoroughly on your system

4. Test Your Changes

# Run all tests
python -m unittest tests.py -v

# Check code quality
prospector main.py

# Test with actual NZBGet installation (if possible)

5. Commit Changes

# Stage your changes
git add .

# Commit with descriptive message
git commit -m "Add support for custom sample patterns

- Implement configurable pattern matching
- Add tests for new pattern functionality
- Update documentation with pattern examples
- Resolves #123"

Good commit messages:

• Start with action verb (Add, Fix, Update, Remove)
• Keep first line under 50 characters
• Add detailed description if needed
• Reference issue numbers when applicable

6. Push and Create Pull Request

# Push to your fork
git push origin feature/your-feature-name

# Create pull request on GitHub
# Use the pull request template if available

📝 Pull Request Guidelines

Pull Request Template

When creating a pull request, include:

Description:

• What does this PR do?
• Why is this change needed?
• How does it work?

Testing:

• How was this tested?
• What test cases were added?
• Any manual testing performed?

Documentation:

• What documentation was updated?
• Are there any breaking changes?

Checklist:

• Tests pass locally
• Code follows style guidelines
• Documentation updated
• Self-review completed

Review Process

What to expect:

1. Automated checks run (tests, code quality)
2. Maintainer review of code and approach
3. Feedback and suggestions for improvements
4. Iteration based on feedback
5. Approval and merge when ready

Review criteria:

• Code quality and style
• Test coverage
• Documentation completeness
• Backward compatibility
• Performance impact

🧪 Testing Guidelines

Test Categories

Unit Tests:

• Test individual functions
• Mock external dependencies
• Fast execution
• High coverage

Integration Tests:

• Test component interactions
• Use realistic data
• Test error conditions
• Validate end-to-end behavior

Test Data

Create realistic test scenarios:

# Good test data
test_files = [
    "Movie.Name.2023.sample.mkv",
    "sample.mp4", 
    "Movie.Name.2023.1080p.mkv",
    "soundtrack.mp3"
]

# Test various edge cases
edge_cases = [
    "movie.resample.mkv",        # False positive prevention
    "SAMPLE.mkv",                # Case sensitivity
    "movie.sample.mkv",          # Mixed case
    "файл.sample.mkv"            # Unicode support
]

Writing Good Tests

def test_sample_pattern_detection(self):
    """Test that sample patterns are correctly identified."""
    # Arrange
    sample_files = ["movie.sample.mkv", "sample.mp4"]
    non_sample_files = ["movie.1080p.mkv", "soundtrack.mp3"]
    
    # Act & Assert
    for file in sample_files:
        self.assertTrue(
            self.extension._matches_sample_pattern(file),
            f"Should detect {file} as sample"
        )
    
    for file in non_sample_files:
        self.assertFalse(
            self.extension._matches_sample_pattern(file),
            f"Should not detect {file} as sample"
        )

📚 Documentation Standards

Code Documentation

Function docstrings:

def process_directory(self, directory_path: str) -> int:
    """
    Process a directory for sample file removal.
    
    Recursively scans the directory and removes files/directories
    that match sample patterns or size criteria.
    
    Args:
        directory_path: Path to the directory to process
        
    Returns:
        Number of items removed (files + directories)
        
    Raises:
        PermissionError: If unable to access directory
        OSError: If directory operations fail
    """

README and Wiki Updates

When updating documentation:

• Keep language clear and concise
• Use examples to illustrate concepts
• Update table of contents if needed
• Test all links and references
• Consider different user skill levels

Code Comments

When to add comments:

• Complex algorithms or logic
• Non-obvious design decisions
• Workarounds for specific issues
• Regex patterns and their purpose

Example:

# Use word boundaries to prevent false positives like "resample"
pattern = r'\bsample\b'

# Check both pattern and size to minimize false removals
if self._matches_pattern(filename) and self._below_threshold(filepath):
    return True

🔒 Security Considerations

File Operations

Be careful with:

• File deletion operations
• Directory traversal
• Permission checks
• Path validation

Input Validation

Always validate:

• File paths and names
• Configuration values
• User inputs
• External data

Security Testing

Consider these scenarios:

• Malicious file names
• Permission boundary testing
• Path traversal attempts
• Large file handling

🎯 Getting Help

Development Questions

For development help:

• GitHub Discussions: General development questions
• GitHub Issues: Specific bugs or feature discussions
• Code Comments: Ask questions in pull request reviews

Resources

Useful links:

• NZBGet Extension Documentation
• Python Style Guide (PEP 8)
• Git Best Practices
• Testing Best Practices

🏆 Recognition

Contributor Recognition

Contributors will be:

• Listed in repository contributors
• Mentioned in release notes
• Credited in documentation updates
• Thanked in project communications

Types of Contributions

All contributions are valued:

• Code improvements
• Bug reports and fixes
• Documentation updates
• Testing and quality assurance
• User support and community help
• Feature suggestions and feedback

📞 Contact

For contributor questions:

• GitHub Discussions: RemoveSamples Discussions
• GitHub Issues: RemoveSamples Issues
• Security Issues: [email protected]

---

Thank you for contributing to RemoveSamples! Your help makes this extension better for everyone. 🚀