hed-python/CONTRIBUTING.md at main

Contributing to HEDTools

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

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

Fork and clone the repository:

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

Create a virtual environment (recommended):

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

Install in development mode:

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

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

To automatically fix issues:
```
ruff check --fix hed/ tests/
```
typos: For spell checking

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

Update your branch:
```
git fetch origin
git rebase origin/main
```
Run all tests:
```
python -m unittest discover tests
```
Check code style:
Update documentation if you've added/changed functionality

Submitting a Pull Request

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes with clear, focused commits

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

Push to your fork:

git push origin feature/your-feature-name

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:

Clear title describing the problem
Environment details: OS, Python version, hedtools version
Steps to reproduce the issue
Expected behavior
Actual behavior
Code sample demonstrating the problem (if applicable)
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