Skip to content

Contributing Guidelines

Thank you for your interest in contributing to hashreport! This document provides guidelines and instructions for contributing to the project.

Development Environment Setup

Prerequisites

  • Python 3.10 or higher (up to 3.14)
  • Git
  • Poetry (Python package manager)
  • Pre-commit hooks

Setting Up the Development Environment

  1. Clone the Repository 

    git clone https://github.com/madebyjake/hashreport.git
cd hashreport

  2. Install Poetry 

    curl -sSL https://install.python-poetry.org | python3 -

  3. Install Dependencies 

    poetry install

  4. Set Up Pre-commit Hooks 

    poetry run pre-commit install

  5. Verify Setup 

    poetry run pytest

Running Tests

Running All Tests

# Run tests with coverage
poetry run pytest --cov=hashreport

# Run tests without coverage
poetry run pytest

# Run tests with verbose output
poetry run pytest -v

Running Specific Tests

# Run a specific test file
poetry run pytest tests/test_scanner.py

# Run a specific test function
poetry run pytest tests/test_scanner.py::test_scan_directory

# Run tests matching a pattern
poetry run pytest -k "test_scan"

Test Coverage

# Generate coverage report
poetry run pytest --cov=hashreport --cov-report=html

# View coverage in browser
open htmlcov/index.html

Code Style

Formatting

We use Black for code formatting:

# Format all Python files
poetry run black .

# Format a specific file
poetry run black hashreport/cli.py

Linting

We use Flake8 for linting:

# Lint all Python files
poetry run flake8

# Lint a specific file
poetry run flake8 hashreport/cli.py

Making Changes

1. Create a Branch

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Or create a bug fix branch
git checkout -b fix/your-bug-fix

2. Make Your Changes

  • Write clear, concise code
  • Add tests for new features
  • Update documentation
  • Follow the code style guidelines

3. Commit Your Changes

We use conventional commits:

# Format: type(scope): description
git commit -m "feat(scanner): add memory-mapped file support"

Types:

Type Description
feat New feature
fix Bug fix
docs Documentation changes
style Code style changes
refactor Code refactoring
test Test changes
chore Maintenance tasks

4. Push Your Changes

git push origin feature/your-feature-name

5. Create a Pull Request

  1. Go to the GitHub repository
  2. Click "New Pull Request"
  3. Select your branch
  4. Fill in the PR template
  5. Submit the PR

Documentation

Updating Documentation

  1. Update Source Code Documentation

    • Add docstrings to new functions
    • Update existing docstrings
    • Follow Google style guide

  2. Update User Documentation

    • Edit files in the docs/ directory
    • Update examples
    • Add new features to relevant sections

  3. Build Documentation 

    poetry run mkdocs build

  4. Preview Documentation 

    poetry run mkdocs serve

Releasing

Releases are published to PyPI via GitHub Actions. Version is derived from Git tags (e.g. v1.2.3) using poetry-dynamic-versioning.

Note: Direct commits to main are not allowed (branch protection). The version bump is done on dev and merged to main via a pull request.

  1. On dev: Ensure all release-ready work is merged.
  2. Bump version and update changelog (on dev): 
    git checkout dev
poetry run cz bump --increment PATCH   # or MINOR, MAJOR
    Commitizen updates CHANGELOG.md and creates a tag (e.g. v1.2.3).
  3. Push dev and the tag: 
    git push origin dev && git push origin --tags
  4. Open a pull request from dev into main. Merge the PR (after status checks pass).
  5. Create a GitHub Release for the new tag (Releases → Draft a new release → choose the tag, add notes, publish).
  6. The Publish to PyPI workflow runs automatically and publishes the package. The workflow uses the pypi environment (Trusted Publishing); ensure it is configured in the repository settings.

Getting Help

License

By contributing, you agree that your contributions will be licensed under the project's AGPL-3.0 License.