Contributing to SimpleFlow¶

Thank you for your interest in contributing to SimpleFlow! This guide will help you get started.

Getting Started¶

Fork and Clone¶

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/simple_flow.git
cd simple_flow

Add the upstream repository:

git remote add upstream https://github.com/madbomber/simple_flow.git

Install Dependencies¶

bundle install

Run Tests¶

bundle exec rake test

Expected output:

77 tests, 296 assertions, 0 failures, 0 errors, 0 skips

Development Workflow¶

1. Create a Branch¶

Create a feature branch from main:

git checkout -b feature/your-feature-name

Branch naming conventions: - feature/ - New features - fix/ - Bug fixes - docs/ - Documentation changes - refactor/ - Code refactoring - test/ - Test additions or improvements

2. Make Your Changes¶

Code Style¶

SimpleFlow follows standard Ruby conventions. Please ensure:

Use 2 spaces for indentation
Keep lines under 120 characters when possible
Add comments for complex logic
Use descriptive variable names

Adding Features¶

When adding a new feature:

Write tests first (TDD approach)
Implement the feature
Update documentation
Add examples if applicable

Fixing Bugs¶

When fixing a bug:

Add a failing test that reproduces the bug
Fix the bug
Ensure the test passes
Consider adding regression tests

3. Run Tests¶

Run the full test suite:

bundle exec rake test

Run a specific test file:

ruby -Ilib:test test/pipeline_test.rb

Run a specific test:

ruby -Ilib:test test/pipeline_test.rb -n test_basic_pipeline

4. Update Documentation¶

If your changes affect user-facing behavior:

Update relevant documentation in docs/
Update the README if needed
Add or update code examples
Update CHANGELOG.md

5. Commit Your Changes¶

Write clear, descriptive commit messages:

git add .
git commit -m "Add feature: parallel execution for named steps

- Implement dependency graph analysis
- Add automatic parallel detection
- Include tests and documentation
"

Commit message guidelines: - Use present tense ("Add feature" not "Added feature") - First line should be under 72 characters - Include a blank line after the first line - Provide detailed description in the body if needed

6. Push and Create Pull Request¶

Push your branch:

git push origin feature/your-feature-name

Create a pull request on GitHub: 1. Go to the SimpleFlow repository 2. Click "New Pull Request" 3. Select your branch 4. Fill out the pull request template 5. Submit for review

Pull Request Guidelines¶

PR Template¶

## Description

Brief description of what this PR does.

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Changes Made

- List of specific changes
- Another change
- And another

## Testing

Describe how you tested your changes:

- [ ] All existing tests pass
- [ ] Added new tests for new functionality
- [ ] Tested manually with examples

## Documentation

- [ ] Updated relevant documentation
- [ ] Updated CHANGELOG.md
- [ ] Added/updated code examples

## Checklist

- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] No new warnings generated
- [ ] Tests added and passing

Code Review Process¶

Automated Checks: GitHub Actions will run tests automatically
Peer Review: A maintainer will review your code
Feedback: Address any requested changes
Approval: Once approved, your PR will be merged

Testing Guidelines¶

Test Structure¶

Tests use Minitest:

require 'test_helper'

class MyFeatureTest < Minitest::Test
  def setup
    # Setup code runs before each test
    @pipeline = SimpleFlow::Pipeline.new
  end

  def test_feature_works
    result = @pipeline.call(SimpleFlow::Result.new(42))

    assert result.continue?
    assert_equal 42, result.value
  end

  def test_handles_errors
    result = @pipeline.call(SimpleFlow::Result.new(nil))

    refute result.continue?
    assert result.errors.any?
  end
end

Test Coverage¶

Aim for comprehensive test coverage:

Test happy paths
Test error conditions
Test edge cases
Test with various data types

Current test coverage: 96.61% (121 tests, 296 assertions)

Running Specific Tests¶

# Run all tests
bundle exec rake test

# Run specific test file
ruby -Ilib:test test/result_test.rb

# Run specific test method
ruby -Ilib:test test/result_test.rb -n test_with_context

Documentation Guidelines¶

Adding Documentation¶

When adding new features, update:

API Reference (docs/api/)
Complete method signatures
Parameters and return values
Examples
Guides (docs/guides/)
How-to guides
Best practices
Real-world examples
README.md
Overview of feature
Quick start example

Documentation Style¶

Use clear, concise language
Include code examples
Cross-reference related documentation
Keep examples practical and realistic

Project Structure¶

simple_flow/
├── lib/
│   └── simple_flow/
│       ├── dependency_graph.rb          # Dependency graph analysis
│       ├── dependency_graph_visualizer.rb # Visualization tools
│       ├── middleware.rb                # Built-in middleware
│       ├── parallel_executor.rb         # Parallel execution
│       ├── pipeline.rb                  # Pipeline orchestration
│       ├── result.rb                    # Result value object
│       ├── step_tracker.rb              # Step tracking
│       └── version.rb                   # Version number
├── test/
│   ├── test_helper.rb                   # Test configuration
│   ├── result_test.rb                   # Result tests
│   ├── pipeline_test.rb                 # Pipeline tests
│   ├── middleware_test.rb               # Middleware tests
│   ├── parallel_execution_test.rb       # Parallel execution tests
│   └── dependency_graph_test.rb         # Graph analysis tests
├── examples/
│   ├── 01_basic_pipeline.rb             # Basic usage
│   ├── 02_error_handling.rb             # Error patterns
│   ├── 03_middleware.rb                 # Middleware examples
│   ├── 04_parallel_automatic.rb         # Auto parallel
│   ├── 05_parallel_explicit.rb          # Explicit parallel
│   ├── 06_real_world_ecommerce.rb       # E-commerce example
│   ├── 07_real_world_etl.rb             # ETL example
│   ├── 08_graph_visualization.rb        # Graph viz
│   └── 09_pipeline_visualization.rb     # Pipeline viz
├── docs/                                # Documentation
└── CHANGELOG.md                         # Change history

Adding Examples¶

When adding examples:

Place in examples/ directory
Use clear, descriptive names
Include comments explaining the code
Make examples runnable
Demonstrate real-world use cases

Example template:

#!/usr/bin/env ruby
# frozen_string_literal: true

require_relative '../lib/simple_flow'

# Description of what this example demonstrates

puts "=" * 60
puts "Example: Your Example Name"
puts "=" * 60
puts

# Your example code here

puts "\n" + "=" * 60
puts "Example completed!"
puts "=" * 60

Releasing¶

(For maintainers only)

Update version in lib/simple_flow/version.rb
Update CHANGELOG.md
Commit changes
Create git tag: git tag v0.x.x
Push tag: git push --tags
Build gem: gem build simple_flow.gemspec
Push to RubyGems: gem push simple_flow-0.x.x.gem

Getting Help¶

Issues: Open an issue on GitHub
Discussions: Use GitHub Discussions for questions
Email: Contact maintainers directly for sensitive issues

Code of Conduct¶

Be respectful and inclusive
Provide constructive feedback
Focus on the code, not the person
Help others learn and grow

License¶

By contributing to SimpleFlow, you agree that your contributions will be licensed under the project's license.

Thank You!¶

Your contributions make SimpleFlow better for everyone. Thank you for taking the time to contribute!