tzst/docs/development.md

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

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

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

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 documentation
├── 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

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

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:

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

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.