Contributing¶

Thank you for your interest in contributing to Rain CLI! This document provides guidelines and information for contributors.

Getting Started¶

Development Setup¶

Fork and Clone

Fork the repository on GitHub and clone your fork:

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

Set up Development Environment

Create a virtual environment and install dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
pip install -r requirements-dev.txt

Install Optional Dependencies

For full functionality during development:
```
pip install netifaces distro GPUtil py-cpuinfo
```
Verify Installation

Test that everything works:
```
rain --version
python -m pytest
```

Project Structure¶

Understanding the codebase:

rain/
├── cli/
│   └── main.py          # Main CLI entry point
├── core/
│   ├── collector.py     # System information collection
│   └── robust_collector.py  # Robust collection with fallbacks
├── tests/
│   └── test_*.py        # Test files
├── docs/
│   ├── conf.py          # Sphinx configuration
│   └── *.rst            # Documentation files
├── setup.py             # Package setup
└── README.md            # Project readme

Key Components¶

CLI Module (``cli/main.py``)

Command-line interface implementation
Argument parsing and validation
Output formatting and display

Core Module (``core/collector.py``)

System information collection
Cross-platform compatibility
Performance optimization

Robust Collector (``core/robust_collector.py``)

Error-resistant collection methods
Graceful degradation
Fallback implementations

How to Contribute¶

Types of Contributions¶

We welcome various types of contributions:

Bug Reports: Help us identify and fix issues
Feature Requests: Suggest new functionality
Code Contributions: Implement features or fix bugs
Documentation: Improve or expand documentation
Testing: Add test coverage or improve existing tests

Reporting Bugs¶

When reporting bugs, please include:

Environment Information: - Operating system and version - Python version - Rain CLI version - Output of rain --json (if relevant)
Steps to Reproduce: - Exact commands that trigger the issue - Expected vs. actual behavior - Any error messages
Additional Context: - Screenshots (if applicable) - System specifications - Other relevant software versions

Bug Report Template:

**Environment**
- OS: [e.g., Ubuntu 20.04, macOS 12.0, Windows 10]
- Python: [e.g., 3.9.7]
- Rain CLI: [e.g., 1.0.0]

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

**Steps to Reproduce**
1. Run `rain ...`
2. See error

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

**Actual Behavior**
What actually happened.

**Additional Context**
Any other relevant information.

Suggesting Features¶

For feature requests, please:

Check Existing Issues: Ensure the feature hasn’t been requested
Describe the Use Case: Explain why this feature would be useful
Propose Implementation: If you have ideas on how to implement it
Consider Scope: Keep features focused and maintainable

Feature Request Template:

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

**Use Case**
Why would this feature be useful? What problem does it solve?

**Proposed Implementation**
If you have ideas on how to implement this feature.

**Alternatives Considered**
Other approaches you've considered.

Code Contributions¶

Development Workflow¶

Create an Issue: Discuss your changes before implementing
Create a Branch: Use descriptive branch names
Make Changes: Follow coding standards and test your changes
Submit a Pull Request: Include a clear description

Branch Naming:

feature/description for new features
fix/description for bug fixes
docs/description for documentation changes

Commit Messages:

Use clear, descriptive commit messages:

Add CPU temperature monitoring for Linux

- Implement temperature collection using /sys/class/thermal
- Add fallback for systems without thermal sensors
- Update tests for new functionality

Closes #123

Coding Standards¶

Python Style:

Follow PEP 8
Use type hints where appropriate
Write docstrings for functions and classes
Keep functions focused and small

Code Quality:

Run tests before submitting: python -m pytest
Check code style: flake8
Ensure type correctness: mypy (if configured)

Example Function:

def get_cpu_temperature() -> Optional[float]:
    """Get CPU temperature in Celsius.

    Returns:
        CPU temperature in Celsius, or None if unavailable.

    Raises:
        OSError: If temperature sensors are not accessible.
    """
    try:
        with open('/sys/class/thermal/thermal_zone0/temp', 'r') as f:
            temp_millidegrees = int(f.read().strip())
            return temp_millidegrees / 1000.0
    except (FileNotFoundError, PermissionError, ValueError):
        return None

Testing¶

Writing Tests:

Add tests for new functionality
Test edge cases and error conditions
Use meaningful test names
Mock external dependencies

Test Categories:

Unit Tests: Test individual functions
Integration Tests: Test component interactions
Platform Tests: Test cross-platform compatibility

Example Test:

def test_get_cpu_temperature_success():
    """Test successful CPU temperature retrieval."""
    with patch('builtins.open', mock_open(read_data='45000')):
        temp = get_cpu_temperature()
        assert temp == 45.0

def test_get_cpu_temperature_file_not_found():
    """Test handling of missing temperature file."""
    with patch('builtins.open', side_effect=FileNotFoundError):
        temp = get_cpu_temperature()
        assert temp is None

Documentation¶

Documentation Types:

User Documentation: How to use Rain CLI
Developer Documentation: How to contribute and extend
API Documentation: Function and module references

Writing Guidelines:

Use clear, concise language
Include practical examples
Keep documentation up-to-date with code changes
Test documentation examples

Building Documentation:

cd docs
sphinx-build -b html . _build/html

Pull Request Process¶

Submission Guidelines¶

Pre-submission Checklist: - [ ] Tests pass locally - [ ] Code follows style guidelines - [ ] Documentation is updated - [ ] Commit messages are clear - [ ] Branch is up-to-date with main
Pull Request Description: - Clear title summarizing changes - Detailed description of what changed - Reference related issues - Include testing notes

Pull Request Template:

## Description
Brief description of changes.

## Changes Made
- List of specific changes
- Another change

## Testing
- How the changes were tested
- Any manual testing performed

## Related Issues
Closes #123

## Screenshots (if applicable)
[Include screenshots for UI changes]

Review Process¶

Automated Checks: CI/CD runs tests and checks
Code Review: Maintainers review code quality and design
Testing: Changes are tested on different platforms
Merge: Approved changes are merged to main branch

Review Criteria:

Code quality and style
Test coverage
Documentation completeness
Performance impact
Cross-platform compatibility

Release Process¶

Rain CLI follows semantic versioning (SemVer):

Major (x.0.0): Breaking changes
Minor (0.x.0): New features, backward compatible
Patch (0.0.x): Bug fixes, backward compatible

Community Guidelines¶

Code of Conduct¶

We are committed to providing a welcoming and inclusive environment:

Be Respectful: Treat everyone with respect and kindness
Be Collaborative: Work together constructively
Be Patient: Help others learn and grow
Be Inclusive: Welcome diverse perspectives and backgrounds

Communication¶

GitHub Issues: Bug reports and feature requests
Pull Requests: Code discussions and reviews
Discussions: General questions and community support

Recognition¶

Contributors are recognized in:

CONTRIBUTORS.md file
Release notes
Project documentation

Getting Help¶

If you need help contributing:

Check Documentation: Start with this guide and user documentation
Search Issues: Look for similar questions or problems
Ask Questions: Open a discussion or issue for help
Contact Maintainers: Reach out directly if needed

Useful Resources:

Thank you for contributing to Rain CLI! Your help makes this project better for everyone.