Development

This section covers development setup, contribution guidelines, and technical details for contributors.

Development Environment

Setting up a development environment for record-shelf:

# Clone the repository
git clone https://github.com/bryankemp/record-shelf.git
cd record-shelf

# Set up development environment
make setup
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install pre-commit hooks
make pre-commit

Development Commands

The project includes several make targets for development:

Testing

make test          # Run all tests
make test-cov      # Run tests with coverage
make qtest         # Quick test run

Code Quality

make lint          # Run all linting tools
make format        # Format code with black and isort
make type-check    # Run mypy type checking
make security      # Run security checks
make dev-test      # Run all development checks

Documentation

make docs          # Build documentation
make docs-serve    # Serve documentation locally
make docs-rebuild  # Clean and rebuild docs

Building and Publishing

make build         # Build package
make clean         # Clean build artifacts
make upload        # Upload to PyPI (maintainers only)

Code Standards

The project follows these coding standards:

  • PEP 8 style guidelines

  • Black for code formatting (88 character line length)

  • isort for import sorting

  • mypy for type checking

  • pylint for additional linting

  • Google-style docstrings

  • Type hints for all functions and methods

Testing Guidelines

  • Write tests for all new features and bug fixes

  • Maintain or improve test coverage (currently >90%)

  • Use pytest for testing framework

  • Mock external API calls in tests

  • Include both unit and integration tests

Project Structure

record_shelf/
├── record_shelf/          # Main package
│   ├── __init__.py
│   ├── cli.py            # Command-line interface
│   ├── config.py         # Configuration management
│   ├── report_generator.py  # Core report generation
│   └── utils.py          # Utility functions
├── tests/                # Test suite
├── docs/                 # Documentation
├── .github/              # GitHub workflows
├── pyproject.toml        # Project configuration
├── Makefile             # Development commands
└── README.md            # Project overview

Release Process

The project uses automated releases via GitHub Actions:

  1. Update version in pyproject.toml

  2. Update CHANGELOG.md

  3. Create and push a git tag: git tag v1.0.0 && git push origin v1.0.0

  4. GitHub Actions will automatically: - Run tests - Build the package - Publish to PyPI - Create a GitHub release

Continuous Integration

The project uses GitHub Actions for CI/CD:

  • CI Pipeline: Runs on every push and pull request - Tests across Python 3.8-3.11 and multiple OS (Ubuntu, Windows, macOS) - Code quality checks (linting, formatting, type checking) - Security scanning - Documentation building

  • Release Pipeline: Runs on git tags - Full test suite - Package building and validation - PyPI publishing - GitHub release creation

For more detailed contribution guidelines, see the CONTRIBUTING.md file.