Contributing to Cronflow

November 1, 2025 · View on GitHub

Thank you for your interest in contributing to Cronflow! This document outlines the development workflow, contribution guidelines, and how to work with our versioning system.

🚀 Quick Start

Create an issue
Fork the repository
Clone your fork: git clone https://github.com/dali-benothmen/cronflow.git
Install dependencies: bun install
Build the project: bun run build:all
Run tests: bun test
Create a feature branch: git checkout -b feature/your-feature-name

🛠️ Development Setup

Prerequisites

Bun >= 1.0.0 (recommended) or Node.js >= 18.0.0
Rust >= 1.70.0 (for core development)
Git

Installation

# Clone the repository
git clone https://github.com/dali-benothmen/cronflow.git
cd cronflow

# Install dependencies
npm install  # or: bun install

# Build the Rust core
cd core
cargo build --release
cd ..

# Build TypeScript
npm run build  # or: bun run build

# Run tests
npm test  # or: bun test

💡 Tip: For a comprehensive setup guide including troubleshooting, see SETUP_GUIDE.md

Available Scripts

# Development
npm run dev              # Start development server with watch mode
npm run dev:test         # Run tests in watch mode

# Building
npm run build            # Build TypeScript + Rust core
npm run build:core       # Build only Rust core
npm run build:prod       # Production build with optimizations

# Testing
npm test                 # Run all tests
npm run test:run         # Run tests once
npm run test:coverage    # Run tests with coverage
npm run test:ui          # Run tests with UI

# Code Quality
npm run lint             # Run ESLint
npm run lint:fix         # Fix ESLint issues
npm run format           # Format code with Prettier
npm run format:check     # Check code formatting

# Package Management
npm run pack             # Create a local .tgz package
npm run analyze          # Analyze bundle size
npm run check:bundle-size # Check bundle size limits
npm run clean            # Clean build artifacts

Note: You can replace npm with bun if you prefer Bun as your runtime

📝 Changesets Workflow

We use Changesets for versioning and publishing. This ensures consistent releases and automatic changelog generation.

How Changesets Work

Changeset Creation: When making changes, create a changeset describing what changed
Version Bumping: Changesets automatically determine the next version based on change types
Release Publishing: Automated publishing to npm with proper changelog

Creating a Changeset

When you make changes that should be included in a release:

# Create a changeset
bunx changeset

This will prompt you to:

Select packages that changed (if multiple)
Choose change type:
- patch - Bug fixes, documentation updates
- minor - New features (backward compatible)
- major - Breaking changes
Write a description of your changes

Changeset Types

# Patch release (0.1.0 → 0.1.1)
bunx changeset
# Select: patch
# Description: "fix: resolve webhook parsing issue"

# Minor release (0.1.0 → 0.2.0)
bunx changeset
# Select: minor
# Description: "feat: add parallel execution support"

# Major release (0.1.0 → 1.0.0)
bunx changeset
# Select: major
# Description: "BREAKING CHANGE: refactor API for better performance"

Example Changeset File

After running bunx changeset, a file like .changeset/blue-cats-smile.md will be created:

---
'cronflow': patch
---

fix: resolve webhook parsing issue in high-traffic scenarios

- Improved error handling for malformed webhook payloads
- Added validation for required webhook headers
- Enhanced logging for debugging webhook issues

Version Management

# Version packages (creates/updates CHANGELOG.md)
bunx changeset version

# Publish to npm
bunx changeset publish

🔄 Pull Request Guidelines

Before Submitting a PR

Create an issue (even if it is a new feature) to notify the community about it
Ensure tests pass: bun test
Check code quality: bun run lint && bun run format:check
Build successfully: bun run build:all
Create changeset (if needed): bunx changeset

PR Title Format

Use conventional commit format:

type(scope): description

Examples:
feat(sdk): add parallel execution support
fix(core): resolve memory leak in job dispatcher
docs(readme): update installation instructions
test(workflow): add integration tests for webhooks

PR Description Template

## Description

Brief description of what this PR accomplishes.

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing

- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist

- [ ] Code follows the style guidelines
- [ ] Self-review completed
- [ ] Changeset created (if needed)
- [ ] Documentation updated (if needed)

## Related Issues

Closes #123

Code Style Guidelines

TypeScript/JavaScript

Indentation: 2 spaces
Quotes: Single quotes for strings
Semicolons: Always use semicolons
Trailing commas: Use trailing commas in objects and arrays
Line length: 80 characters max

// Good
const config = {
  name: 'cronflow',
  version: '0.1.0',
  description: 'Workflow automation engine',
};

// Bad
const config = {
  name: 'cronflow',
  version: '0.1.0',
  description: 'Workflow automation engine',
};

Rust

Indentation: 4 spaces
Line length: 100 characters max
Naming: snake_case for variables and functions
Documentation: Include doc comments for public APIs

/// Executes a workflow step with the given context
pub fn execute_step(&self, step_id: &str, context: &Context) -> CoreResult<StepResult> {
    // Implementation
}

Commit Message Guidelines

Follow Conventional Commits format:

type(scope): description

[optional body]

[optional footer]

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples

# Good commit messages
feat(sdk): add parallel execution support
fix(core): resolve memory leak in job dispatcher
docs(readme): update installation instructions
test(workflow): add integration tests for webhooks

# Bad commit messages
added stuff
fixed bug
updated docs

🧪 Testing Guidelines

Writing Tests

Unit tests: Test individual functions and classes
Integration tests: Test component interactions
End-to-end tests: Test complete workflows

Test Structure

// Unit test example
describe('WorkflowBuilder', () => {
  describe('step()', () => {
    it('should add a step to the workflow', () => {
      const workflow = new WorkflowBuilder();
      workflow.step('test-step', async ctx => ({ result: 'success' }));

      expect(workflow.steps).toHaveLength(1);
      expect(workflow.steps[0].id).toBe('test-step');
    });
  });
});

Running Tests

# Run all tests
bun test

# Run tests in watch mode
bun run dev:test

# Run tests with coverage
bun run test:coverage

# Run specific test file
bun test tests/workflow.test.ts

📚 Documentation Guidelines

Code Documentation

Public APIs: Always include JSDoc comments
Complex logic: Add inline comments explaining the reasoning
Examples: Include usage examples in documentation

/**
 * Creates a new workflow instance
 * @param name - The name of the workflow
 * @param options - Configuration options
 * @returns A new workflow builder instance
 * @example
 * ```typescript
 * const workflow = new WorkflowBuilder('my-workflow', {
 *   timeout: 30000,
 *   retries: 3
 * });
 * ```
 */
export class WorkflowBuilder {
  constructor(name: string, options?: WorkflowOptions) {
    // Implementation
  }
}