Contributing Guide

Date:

2026-03-13

1 Contributing to NEB Orchestrator

Thank you for your interest in contributing to NEB Orchestrator!

2 Table of Contents

3 Getting Started

3.1 Fork and Clone

# Fork on GitHub, then clone
git clone https://github.com/YOUR_USERNAME/eon_orchestrator.git
cd eon_orchestrator
git remote add upstream https://github.com/HaoZeke/eon_orchestrator.git

3.2 Set Up Development Environment

# Install development dependencies
pip install snakemake>=7.0 pre-commit

# Install pre-commit hooks
pre-commit install

4 How to Contribute

4.1 Reporting Bugs

Before creating bug reports, please check existing issues. When creating a bug report, include:

  • Clear title and description

  • Steps to reproduce

  • Expected vs actual behavior

  • Snakemake version

  • Configuration file (with paths redacted)

  • Error messages and logs

4.2 Suggesting Enhancements

Enhancement suggestions are welcome! Please provide:

  • Clear description of the enhancement

  • Motivation and use case

  • Examples of how it would work

  • Discussion of alternatives considered

4.3 Pull Requests

  1. Create a feature branch from main

  2. Make your changes

  3. Write or update tests

  4. Update documentation

  5. Run pre-commit checks

  6. Submit PR with clear description

5 Development Workflow

5.1 Branch Naming

  • feature/description: New features

  • fix/description: Bug fixes

  • docs/description: Documentation updates

  • refactor/description: Code refactoring

5.2 Commit Messages

Follow Conventional Commits:

feat: add DFT validation step
fix: correct force convergence threshold
docs: update configuration reference
refactor: simplify NEB rule structure

5.3 Code Style

  • Python: PEP 8 with Black formatting

  • Snakemake: Follow Snakemake best practices

  • Documentation: Orgmode format

  • Line length: 88 characters (Python), 100 (Snakemake)

6 Adding New Rules

When adding a new workflow rule:

  1. Create workflow/rules/your_rule.smk

  2. Include comprehensive docstring

  3. Define clear inputs and outputs

  4. Use parameters for configurability

  5. Add conda environment in workflow/envs/

  6. Update main Snakefile

  7. Document in docs/orgmode/reference/rules.org

  8. Add tests in tests/

6.1 Example Rule Structure

# -*- mode: snakemake; -*-
"""
Rule description with purpose and methodology.

References
----------
- Citation 1
- Citation 2
"""

rule your_rule_name:
    """
    Detailed rule docstring.

    Parameters
    ----------
    config['your_param'] : type
        Description with default value
    """
    input:
        # Input files
    output:
        # Output files
    params:
        # Parameters from config
    conda:
        "envs/your_env.yaml"
    run:
        # Implementation

7 Testing

7.1 Workflow Validation

# Dry run
snakemake -n --configfile config/config.yaml

# Generate rulegraph
snakemake --rulegraph > test_rulegraph.dot

7.2 Example Testing

# Test with HCN example
cd examples/hcn_isom
snakemake -n --configfile config.yaml

8 Documentation

8.1 Building Documentation

cd docs/source
pip install sphinx shibuya
sphinx-build -b html . _build/html

8.2 Documentation Standards

  • Tutorials: Follow Diataxis tutorial quadrant

  • Reference: Comprehensive, structured, no opinions

  • Explanation: Context, background, why not how

  • How-to: Problem-focused, step-by-step

9 Code of Conduct

Please read and follow our Code of Conduct.

10 Questions?

11 License

By contributing, you agree that your contributions will be licensed under the MIT License. See LICENSE file for details.