Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
219 lines (152 loc) · 3.95 KB

CONTRIBUTING.md

File metadata and controls

219 lines (152 loc) · 3.95 KB

Contributing to NGPC

We need YOU! One person can't validate 24 patterns × 18 domains.

Ways to Contribute

1. Test a Pattern 🧪

  • Pick ONE pattern that interests you
  • Implement in your project
  • Report results (even failures help!)

Template:

## Pattern Tested: MAGNETAR

**Domain**: Web backend  
**Use Case**: API request validation  
**Result**: ✅ Success / ❌ Failed  

**Metrics**:
- Requests/sec: 15,000 (vs baseline 12,000)
- Error rate: 0.02% (vs baseline 1.2%)
- CPU usage: +5%

**Notes**: Works great for Byzantine client detection. 
Suggest: Add configurable alignment_strength per use case.

2. Write Examples 📝

  • Create working example in your language
  • Add to experiments/<language>/
  • Document usage

3. Add Benchmarks 📊

  • Compare vs existing solution
  • Share methodology
  • Provide reproducible code

4. Improve Docs 📖

  • Fix typos
  • Add clarifications
  • Translate to other languages

5. Port to Other Languages 🌍

  • Rust (performance)
  • Go (cloud-native)
  • TypeScript (web)
  • Java (enterprise)

Getting Started

  1. Fork the repo
  2. Clone your fork
  3. Create branch: git checkout -b my-contribution
  4. Make changes
  5. Test: Run existing tests
  6. Commit: Clear commit messages
  7. Push: git push origin my-contribution
  8. PR: Open pull request

Code Style

Python

# Follow PEP 8
# Type hints required
def magnetar_align(nodes: List[Node], strength: float = 0.3) -> None:
    """Force Byzantine nodes toward consensus.
    
    Args:
        nodes: List of network nodes
        strength: Alignment strength (0.0-1.0)
    """
    pass

Documentation

  • Code examples must be runnable
  • Include expected output
  • Explain why, not just how

Testing Requirements

New Patterns

def test_new_pattern():
    pattern = NewPattern()
    result = pattern.process(test_data)
    
    # Must pass
    assert result.is_valid()
    assert result.performance > baseline
    
def benchmark_new_pattern():
    # Must include benchmark vs existing solution
    assert new_pattern_time < existing_solution_time

New Languages

  • Must pass all pattern tests
  • Must match Python reference behavior
  • Must include benchmarks

Documentation Requirements

New Pattern

## PATTERN_NAME

**Technical Name**: Clear technical description

**What it does**: One sentence explanation

**Cosmic Analogy**: Brief cosmic explanation

**Code**: Working, runnable example

**Use Cases**: 3-5 concrete use cases

**Beats**: What it replaces

**Benchmark**: Performance data

New Use Case

## Use Case: Title

**Pattern**: Which pattern(s)

**Domain**: Industry/field

**Problem**: What problem it solves

**Solution**: How pattern solves it

**Code**: Implementation example

**Result**: Measured outcome

Review Process

  1. Automated checks: CI runs tests
  2. Code review: Maintainer reviews
  3. Discussion: Ask questions, clarify
  4. Approval: Merge when ready

Timeline: 1-7 days typical

Good First Issues

Labels: good-first-issue, help-wanted

Examples:

  • Add type hints to module X
  • Write test for pattern Y
  • Benchmark pattern Z vs tool W
  • Translate doc to language L
  • Fix typo in file F

Community Guidelines

Be Respectful

  • Constructive feedback only
  • Assume good intentions
  • Disagree politely

Be Helpful

  • Answer questions
  • Share knowledge
  • Welcome newcomers

Be Honest

  • Report failures too
  • Share limitations
  • Admit unknowns

License

By contributing, you agree your contributions will be licensed under MIT License.

Recognition

Contributors are:

  • Listed in CONTRIBUTORS.md
  • Mentioned in release notes
  • Credited in papers/talks (if desired)

Questions?

Thank you for helping validate cosmic computing! 🌌