Contributing¶

Welcome to the Annotation Garden Initiative! We appreciate your interest in contributing to open neuroscience annotation infrastructure.

Ways to Contribute¶

Contributing Annotations¶

1. Choose a Stimulus Repository¶

Browse available repositories in the Annotation-Garden organization:

• Natural Scenes Dataset annotations
• StudyForrest temporal annotations
• HBN Movies annotations (pointer-based)

2. Fork and Clone¶

git clone https://github.com/YOUR_USERNAME/stimulus-repo
cd stimulus-repo

3. Create Annotation Branch¶

git checkout -b add-annotations-your-name

4. Add Your Annotations¶

Follow the annotation format:

annotations/
└── your-annotation-type/
    ├── events.tsv
    └── events.json

5. Validate Annotations¶

# Validate HED strings
hedit validate "$(cat annotations/hed-tags/events.tsv | tail -1 | cut -f4)"

# Or validate all
python scripts/validate_annotations.py

6. Submit Pull Request¶

git add .
git commit -m "Add HED annotations for stimuli 001-100"
git push origin add-annotations-your-name

Then create a Pull Request on GitHub.

Reporting Issues¶

Bug Reports¶

For bug reports, please include:

1. Environment: OS, Python version, package versions
2. Steps to reproduce: Minimal example that reproduces the issue
3. Expected behavior: What should happen
4. Actual behavior: What actually happens
5. Error messages: Full traceback if available

Example:

## Bug Report

**Environment:**
- OS: macOS 14.1
- Python: 3.12.0
- hedit: 0.6.1-alpha2

**Steps to Reproduce:**
1. Run `hedit annotate "test"`
2. Observe error

**Expected:** HED annotation output
**Actual:** `ConnectionError: ...`

**Full Error:**

Feature Requests¶

For feature requests:

1. Use case: Describe why you need this feature
2. Proposed solution: How you envision it working
3. Alternatives: Other approaches you've considered

Code Contributions¶

Development Workflow¶

1. Fork the repository
2. Clone your fork
3. Create branch from develop (not main)
4. Make changes with atomic commits
5. Test your changes
6. Submit PR to develop

Branching Strategy¶

Commit Messages¶

Write clear, concise commit messages:

Add HED validation caching for improved performance

- Cache schema loads to avoid repeated file reads
- Add TTL-based cache invalidation
- Improve validation speed by 3x for batch operations

Don't:

• Use emojis
• Mention AI/Claude co-authorship
• Write vague messages like "fix bug"

Code Style¶

See Code Style Guide for details:

• Python: Ruff for linting and formatting
• TypeScript: ESLint + Prettier
• Tests: pytest with coverage, no mocks

Documentation¶

Building Docs Locally¶

cd documentation
pip install -e .
mkdocs serve

Visit http://localhost:8000 to preview.

Documentation Style¶

• Use clear, concise language
• Include code examples
• Add screenshots for UI features
• Link to related documentation

Community¶

Communication¶

• GitHub Issues: Bug reports, feature requests
• GitHub Discussions: General questions, ideas
• Pull Requests: Code and documentation contributions

Code of Conduct¶

We follow the Contributor Covenant. Be respectful, inclusive, and constructive.

Recognition¶

Contributors are recognized in:

• Repository CONTRIBUTORS files
• Release notes
• Project documentation

Thank you for contributing to open neuroscience!