Skip to content

Contributing to Thyra

Thank you for your interest in contributing to Thyra! This document provides guidelines for contributing to this project.

Table of Contents

Development Environment Setup

Prerequisites

  • Python 3.11 or 3.12
  • Poetry for dependency management
  • Git

Setup Steps

  1. Fork and Clone the Repository 

    git clone https://github.com/<your-username>/thyra.git
cd thyra

  2. Install Dependencies 

    poetry install

  3. Install Pre-commit Hooks (Recommended) 

    poetry run pre-commit install

  4. Verify Installation 

    poetry run pytest -m "not integration"

Code Style Guidelines

We use automated tools to maintain consistent code style:

Formatting

  • Black for code formatting
  • isort for import sorting
  • Line length: 88 characters (Black default)

Linting

  • flake8 for code linting
  • bandit for security checks

Type Hints

  • Use type hints for all public functions
  • Follow PEP 484 conventions

Running Code Quality Checks

# Format code
poetry run black .
poetry run isort .

# Run linting
poetry run flake8

# Run security checks
poetry run bandit -r thyra/

Testing Requirements

Test Types

  1. Unit Tests - Fast tests for individual functions 

    poetry run pytest -m "not integration"

  2. Integration Tests - End-to-end workflow tests 

    poetry run pytest -m "integration"

Test Coverage

  • Aim for >80% code coverage for new code
  • Run tests with coverage: 
    poetry run pytest --cov=thyra --cov-report=html

Writing Tests

  • Place unit tests in tests/unit/
  • Place integration tests in tests/integration/
  • Use descriptive test names: test_should_convert_imzml_when_valid_file_provided
  • Mark tests appropriately: @pytest.mark.unit or @pytest.mark.integration

Pull Request Process

Before Submitting

  1. Create a Feature Branch 

    git checkout -b feature/your-feature-name

  2. Make Your Changes

  3. Follow code style guidelines
  4. Add tests for new functionality

  5. Update documentation if needed

  6. Run Quality Checks 

    poetry run black .
poetry run isort .
poetry run flake8
poetry run pytest

  7. Commit Your Changes

  8. Use clear, descriptive commit messages
  9. Follow conventional commit format when possible: 
    feat: add dry-run mode for conversion preview
fix: resolve memory leak in large dataset processing
docs: update installation instructions

Submitting the Pull Request

  1. Push Your Branch 

    git push origin feature/your-feature-name

  2. Open a Pull Request

  3. Use the provided PR template
  4. Fill out all sections completely

  5. Link related issues

  6. Respond to Review Feedback

  7. Address all reviewer comments
  8. Make requested changes promptly
  9. Ask questions if feedback is unclear

Issue Reporting Guidelines

Before Opening an Issue

  1. Check Existing Issues - Search for similar issues first
  2. Reproduce the Problem - Ensure you can consistently reproduce the issue
  3. Gather Information - Collect relevant system info, error messages, and sample data (if shareable)

Issue Types

Use the appropriate issue template:

  • Bug Report - For reporting software defects
  • Feature Request - For suggesting new functionality
  • Question - For general questions about usage

Information to Include

For Bug Reports: - Operating system and version - Python version - Thyra version - Input file format and size (if relevant) - Complete error message and stack trace - Steps to reproduce

For Feature Requests: - Clear description of the desired functionality - Use case and motivation - Proposed implementation approach (if you have ideas)

Communication Channels

Getting Help

  • GitHub Issues - For bug reports and feature requests
  • GitHub Discussions - For general questions and community discussions

Contributing to Documentation

  • Documentation source is in the docs/ folder
  • Use clear, concise language
  • Include code examples where appropriate
  • Test all code examples

Development Workflow

Typical Contribution Flow

  1. Choose an Issue
  2. Look for issues labeled good-first-issue if you're new

  3. Comment on the issue to indicate you're working on it

  4. Develop Your Solution

  5. Follow the development environment setup
  6. Make small, focused commits

  7. Write tests as you go

  8. Test Thoroughly

  9. Run the full test suite
  10. Test with different input formats if relevant

  11. Verify performance impact for large datasets

  12. Document Your Changes

  13. Update docstrings for modified functions
  14. Update user documentation if needed
  15. Add changelog entry for significant changes

Code of Conduct

Please note that this project is governed by our Code of Conduct. By participating, you agree to abide by its terms.

Versioning Policy

Thyra follows Semantic Versioning (SemVer):

Version Format: MAJOR.MINOR.PATCH

  • MAJOR - Incremented for incompatible API changes
  • MINOR - Incremented for backwards-compatible functionality additions
  • PATCH - Incremented for backwards-compatible bug fixes

Release Process

  1. Automated Versioning - We use python-semantic-release for automated version bumping

  2. Commit Message Format - Use conventional commits to trigger appropriate version bumps: 

    feat: add new converter format (triggers MINOR)
fix: resolve memory leak (triggers PATCH)
feat!: redesign API structure (triggers MAJOR)

  3. Breaking Changes - Always include ! in commit type or BREAKING CHANGE: in footer

  4. Changelog - Automatically generated from commit messages

Development Versions

  • Alpha/Beta releases may be created for testing: 1.2.0-alpha.1
  • Release candidates before major releases: 2.0.0-rc.1

Questions?

If you have questions about contributing that aren't covered here, please:

  1. Check the existing GitHub Discussions
  2. Open a new discussion if your question hasn't been asked
  3. Tag maintainers if you need urgent clarification

Thank you for contributing to Thyra!