Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
351 lines (243 loc) · 8.04 KB

CONTRIBUTING.md

File metadata and controls

351 lines (243 loc) · 8.04 KB

Contributing to HEDTools

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

Table of Contents

Code of Conduct

This project adheres to a code of conduct that we expect all contributors to follow. Please be respectful and constructive in all interactions.

How Can I Contribute?

Types of Contributions

  • Bug Reports: Help us identify and fix issues
  • Feature Requests: Suggest new functionality
  • Code Contributions: Submit bug fixes or new features
  • Documentation: Improve guides, examples, or API docs
  • Testing: Add test coverage or report test failures
  • Examples: Share use cases and example code

Development Setup

Prerequisites

  • Python 3.10 or higher
  • Git
  • pip (Python package manager)

Setting Up Your Development Environment

  1. Fork and clone the repository:

    git clone https://github.com/YOUR_USERNAME/hed-python.git
cd hed-python

  2. Create a virtual environment (recommended):

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install in development mode:

    pip install -e .[dev,test,docs,examples]

  4. Initialize git submodules:

    HED-Python uses git submodules for test data and schemas. Initialize them with:

    git submodule update --init --recursive

    This will fetch:

    • spec_tests/hed-examples/ - Example datasets for specification tests
    • spec_tests/hed-tests/ - Official HED specification tests
    • spec_tests/hed-schemas/ - Official HED schema repository for testing

    Note: The submodule contents are not stored in the hed-python repository. They are fetched on-demand and ignored by git.

  5. Run tests to verify setup:

    python -m unittest discover tests

Coding Standards

Python Style Guide

  • Follow PEP 8 style guidelines
  • Maximum line length: 120 characters
  • Use descriptive variable and function names
  • Add docstrings to all public classes and functions

Code Quality Tools

We use several tools to maintain code quality:

  • ruff format: For automatic code formatting

    # Check if code is formatted correctly
ruff format --check .

# Automatically format all code
ruff format .

# Format specific files or directories
ruff format hed/ tests/

  • ruff: For linting, style checking, and import sorting

    ruff check hed/ tests/

    To automatically fix issues:

    ruff check --fix hed/ tests/

  • typos: For spell checking

    typos

Documentation Style

  • Use Google-style docstrings for all public APIs
  • Include type hints where appropriate
  • Provide examples for complex functionality

Example docstring:

def validate_hed_string(hed_string, schema)->list[dict]:
    """Validate a HED string against a schema.
    
    Parameters:
        hed_string (str): The HED string to validate.
        schema (HedSchema): The schema to validate against.
        
    Returns:
        list: A list of validation issues, empty if valid.
        
    Example:
        >>> schema = load_schema_version('8.4.0')
        >>> issues = validate_hed_string("Event", schema)
        >>> if not issues:
        ...     print("Valid!")
    """
    pass

Testing Guidelines

Test Structure

  • Place tests in the tests/ directory, mirroring the hed/ structure
  • Name test files with test_ prefix
  • Use descriptive test method names

Writing Tests

  • Each test should be independent and isolated
  • Use unittest framework (the project standard)
  • Test both success and failure cases
  • Include edge cases

Example test:

import unittest
from hed import HedString, load_schema

class TestHedValidation(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        cls.schema = load_schema_version('8.4.0')
    
    def test_valid_hed_string(self):
        hed_string = HedString("Event", self.schema)
        issues = hed_string.validate()
        self.assertEqual(len(issues), 0)
    
    def test_invalid_hed_string(self):
        hed_string = HedString("InvalidTag", self.schema)
        issues = hed_string.validate()
        self.assertGreater(len(issues), 0)

if __name__ == '__main__':
    unittest.main()

Running Tests

Run all tests:

python -m unittest discover tests

Run specific test file:

python -m unittest tests/models/test_hed_string.py

Run specific test case:

python -m unittest tests.models.test_hed_string.TestHedString.test_constructor

Pull Request Process

Before Submitting

  1. Update your branch:

    git fetch origin
git rebase origin/main

  2. Run all tests:

    python -m unittest discover tests

  3. Check code style:

    ruff check hed/ tests/

  4. Update documentation if you've added/changed functionality

Submitting a Pull Request

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes with clear, focused commits

  3. Write descriptive commit messages:

    Add validation for temporal extent

- Implement temporal extent validation logic
- Add unit tests for temporal validation
- Update documentation with temporal examples

  4. Push to your fork:

    git push origin feature/your-feature-name

  5. Open a Pull Request on GitHub:

    • Target the main branch
    • Fill out the PR template completely
    • Link related issues
    • Add meaningful description of changes

PR Review Process

  • A maintainer will review your PR within a few days
  • Address any requested changes
  • Once approved, a maintainer will merge your PR

Reporting Bugs

Before Submitting a Bug Report

  • Check the existing issues
  • Update to the latest version
  • Verify the bug is reproducible

How to Submit a Bug Report

Create an issue with:

  1. Clear title describing the problem
  2. Environment details: OS, Python version, hedtools version
  3. Steps to reproduce the issue
  4. Expected behavior
  5. Actual behavior
  6. Code sample demonstrating the problem (if applicable)
  7. Error messages or stack traces

Example:

## Bug: Schema validation fails with custom schema

**Environment:**
- OS: Ubuntu 22.04
- Python: 3.10.5
- hedtools: 0.5.0

**Steps to Reproduce:**
1. Load custom schema from file
2. Validate HED string with tag "Event"
3. Observe error

**Expected:** Validation succeeds
**Actual:** Raises KeyError

**Code:**
\```python
from hed import load_schema, HedString
schema = load_schema('/path/to/schema.xml')
hed = HedString("Event")
issues = hed.validate(schema)  # KeyError here
\```

**Error:**
\```
KeyError: 'Event'
  at line 123 in validator.py
\```

Suggesting Enhancements

How to Suggest an Enhancement

Create an issue with:

  1. Clear title describing the enhancement
  2. Use case: Why is this enhancement needed?
  3. Proposed solution: How should it work?
  4. Alternatives considered: Other approaches you've thought about
  5. Additional context: Screenshots, mockups, or examples

Questions?

Thank you for contributing to HEDTools! 🎉