Development Guide

This guide provides comprehensive information for developers contributing to or working with the tzst library.

Setting up Development Environment

This project uses modern Python packaging standards:

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e .[dev]

The development installation includes all necessary tools:

pytest - Testing framework
ruff - Linting and formatting
coverage - Code coverage analysis
sphinx - Documentation generation

Running Tests

Basic Test Commands

# Run all tests
python -m pytest

# Run tests with coverage
pytest --cov=tzst --cov-report=html

# Or use the simpler command (coverage settings are in pyproject.toml)
pytest

# Run with verbose output
python -m pytest -v

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

# 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

Use descriptive test names:

def test_create_archive_with_compression_level_9():

Use fixtures for common test data:

def test_extract_archive(sample_archive_path, temp_dir):

Test edge cases:
- Empty files
- Large files
- Invalid inputs
- Corrupted archives

Add markers for test categorization:

@pytest.mark.integration
def test_full_archive_workflow():

Code Quality

Running Code Style Tools

# Check code quality
ruff check src tests

# Fix auto-fixable issues
ruff check --fix src tests

# Format code
ruff format src tests

# Check formatting without making changes
ruff format --check src tests

Configuration

Settings are defined in pyproject.toml:

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

Code Style Guidelines

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

Documentation

Building Documentation

# Navigate to docs directory
cd docs

# Install documentation dependencies
pip install -r requirements.txt

# Build HTML documentation
make html

# On Windows, use:
make.bat html

# View built documentation
# Open docs/_build/html/index.html in your browser

Documentation Structure

docs/
├── index.md           # Main documentation landing page
├── quickstart.md      # Getting started guide
├── performance.md     # Performance guide and comparisons
├── examples.md        # Usage examples
├── development.md     # This development guide
├── api/               # API reference documentation
│   ├── index.md
│   ├── core.md
│   ├── cli.md
│   └── exceptions.md
├── conf.py           # Sphinx configuration
└── requirements.txt  # Documentation dependencies

Writing Documentation

Use MyST Markdown format
Include code examples for new features
Add cross-references using proper syntax
Test all code snippets to ensure they work

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
├── docs/               # Documentation source
├── .github/            # GitHub workflows and templates
├── pyproject.toml      # Project configuration
├── README.md           # Project Readme
├── LICENSE             # BSD 3-Clause License
└── CONTRIBUTING.md     # Contribution guidelines

Contributing Workflow

1. Making Changes

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

2. 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

3. Pull Request Process

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes following the guidelines above
Add tests for new functionality
Update documentation if needed

Run the test suite:

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

Commit your changes:

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

Push to your fork:

git push origin feature/your-feature-name

Create a pull request using the provided template

4. 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

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

Release Process

Releases are handled by maintainers:

Update version in src/tzst/__init__.py
Create a release tag
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:

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

Suggesting Features

When suggesting features:

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

Code of Conduct

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

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.