tzst/CONTRIBUTING.md

Contributing to tzst

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

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• Project Structure
• Making Changes
• Testing
• Code Style
• Submitting Changes
• Release Process
• Getting Help

Code of Conduct

This project follows the principles of respectful collaboration. Please be kind, constructive, and professional in all interactions.

Getting Started

Prerequisites

• Python 3.12 or higher
• Git
• Basic knowledge of tar archives and compression

Development Setup

1. Fork and clone the repository:

   git clone https://github.com/xixu-me/tzst.git
   cd tzst
   

2. Create a virtual environment:

   python -m venv venv
   # On Windows
   venv\Scripts\activate
   # On Unix/macOS
   source venv/bin/activate
   

3. Install the package in development mode:

   pip install -e .[dev]
   

4. Verify the installation:

   python -m pytest tests/
   

Project Structure

tzst/
├── src/tzst/           # Main package source code
│   ├── __init__.py     # Package initialization and exports
│   ├── __main__.py     # CLI entry point
│   ├── cli.py          # Command-line interface
│   ├── core.py         # Core archive functionality
│   └── exceptions.py   # Custom exceptions
├── tests/              # Test suite
│   ├── conftest.py     # Pytest configuration and fixtures
│   ├── test_core.py    # Core functionality tests
│   ├── test_cli.py     # CLI tests
│   └── test_*.py       # Additional test modules
├── .github/            # GitHub workflows and templates
├── pyproject.toml      # Project configuration
├── README.md           # Project documentation
├── LICENSE             # BSD 3-Clause License
└── CONTRIBUTING.md     # This file

Making Changes

Types of Contributions

We welcome various types of contributions:

• Bug fixes: Fix issues in existing functionality
• Features: Add new capabilities to the library
• Documentation: Improve or add documentation
• Tests: Add or improve test coverage
• Performance: Optimize existing code
• Security: Address security vulnerabilities

Branch Naming

Use descriptive branch names:

• feature/add-streaming-mode
• fix/handle-corrupted-archives
• docs/improve-api-documentation
• test/add-compression-tests

Commit Messages

Follow conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• test: Adding or modifying tests
• refactor: Code refactoring
• perf: Performance improvements
• chore: Build process or auxiliary tool changes

Examples:

feat(core): add streaming compression support

fix(cli): handle invalid archive paths gracefully

docs(readme): update installation instructions

Testing

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov

# Run specific test file
python -m pytest tests/test_core.py

# Run with verbose output
python -m pytest -v

# Run integration tests only
python -m pytest -m integration

Test Structure

• Unit tests: Test individual functions and methods
• Integration tests: Test component interactions
• CLI tests: Test command-line interface
• Platform-specific tests: Test OS-specific functionality

Writing Tests

1. Use descriptive test names:

   def test_create_archive_with_compression_level_9():
   

2. Use fixtures for common test data:

   def test_extract_archive(sample_archive_path, temp_dir):
   

3. Test edge cases:

   • Empty files
   • Large files
   • Invalid inputs
   • Corrupted archives

4. Add markers for test categorization:

   @pytest.mark.integration
   def test_full_archive_workflow():
   

Code Style

This project uses Ruff for linting and formatting.

Configuration

Settings are defined in pyproject.toml:

• Line length: 88 characters
• Target Python version: 3.12+
• Import sorting with isort
• Quote style: double quotes

Running Code Style Tools

# Check code style
ruff check .

# Fix auto-fixable issues
ruff check --fix .

# Format code
ruff format .

# Check formatting without making changes
ruff format --check .

Code Style Guidelines

1. Follow PEP 8 with project-specific modifications
2. Use type hints for all public APIs
3. Write docstrings for classes and public methods
4. Keep functions focused and reasonably sized
5. Use meaningful variable names
6. Add comments for complex logic

Documentation Strings

Use Google-style docstrings:

def create_archive(
    archive_path: str | Path,
    files: Sequence[str | Path],
    compression_level: int = 3,
) -> None:
    """Create a new tzst archive containing the specified files.
    
    Args:
        archive_path: Path where the archive will be created.
        files: Sequence of file/directory paths to include.
        compression_level: Zstandard compression level (1-22).
        
    Raises:
        TzstArchiveError: If archive creation fails.
        FileNotFoundError: If input files don't exist.
    """

Submitting Changes

Pull Request Process

1. Create a feature branch:

   git checkout -b feature/your-feature-name
   

2. Make your changes following the guidelines above

3. Add tests for new functionality

4. Update documentation if needed

5. Run the test suite:

   python -m pytest
   ruff check .
   ruff format --check .
   

6. Commit your changes:

   git add .
   git commit -m "feat: add your feature description"
   

7. Push to your fork:

   git push origin feature/your-feature-name
   

8. Create a pull request using the provided template

Pull Request Guidelines

• Fill out the PR template completely
• Link related issues using keywords (fixes #123)
• Keep PRs focused - one feature/fix per PR
• Ensure all CI checks pass
• Respond to review feedback promptly

Review Process

1. Automated checks must pass (CI/CD, code style)
2. Code review by maintainers
3. Address any feedback or requested changes
4. Final approval and merge by maintainers

Release Process

Releases are handled by maintainers:

1. Update version in src/tzst/__init__.py
2. Create a release tag
3. Automated CI/CD publishes to PyPI

Getting Help

Resources

• Issues: GitHub Issues
• Discussions: Use GitHub Discussions for questions
• Documentation: Check the README and code comments

Reporting Issues

When reporting bugs:

1. Use the bug report template
2. Provide a minimal reproduction case
3. Include system information (OS, Python version)
4. Attach relevant files if possible (archives, logs)

Suggesting Features

When suggesting features:

1. Use the feature request template
2. Explain the use case and motivation
3. Consider backwards compatibility
4. Provide implementation ideas if you have them

Development Tips

Performance Considerations

• Use streaming for large files
• Consider memory usage patterns
• Profile code for bottlenecks
• Test with various file sizes

Security Considerations

• Validate all user inputs
• Use secure defaults (e.g., 'data' filter)
• Handle malicious archives safely
• Be cautious with file paths

Compatibility

• Support Python 3.12+
• Test on multiple platforms (Windows, macOS, Linux)
• Consider different filesystem behaviors
• Maintain backwards compatibility when possible

Recognition

Contributors are recognized in several ways:

• Listed in release notes for significant contributions
• Mentioned in README acknowledgments
• GitHub contributor statistics

Thank you for contributing to tzst! Your efforts help make this library better for everyone.