Contributing to Spry

Thank you for your interest in contributing to Spry! We welcome contributions in all forms - whether it's reporting bugs, suggesting features, improving documentation, or submitting code.

Ways to Contribute

There are many ways to contribute to Spry:

• Report Bugs - Help us identify and fix issues
• Suggest Features - Share ideas for new capabilities
• Improve Documentation - Help make our docs clearer and more comprehensive
• Write Code - Submit pull requests to fix bugs or add features
• Help Others - Answer questions in discussions and issues
• Share Examples - Show the community what you've built with Spry

Getting Started

Prerequisites

Before contributing to Spry, ensure you have:

• Deno 2.5+ installed
• Git installed
• A GitHub account
• Familiarity with TypeScript and Markdown

Setting Up Your Development Environment

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

git remote add upstream https://github.com/programmablemd/spry.git

deno cache --reload lib/mod.ts

deno test

Development Workflow

Creating a Branch

Always create a new branch for your work:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Use descriptive branch names:

• feature/add-python-support
• fix/sql-parsing-error
• docs/improve-quickstart

Making Changes

deno test

git add .
git commit -m "feat: add Python execution support"

Commit Message Guidelines

We follow the Conventional Commits specification:

Examples:

feat: add PostgreSQL connection pooling
fix: resolve SQL injection vulnerability
docs: update installation guide for Windows
refactor: simplify task dependency resolution

Submitting Pull Requests

Before Submitting

git fetch upstream
git rebase upstream/main

deno test

deno fmt

deno lint

Creating the Pull Request

git push origin feature/your-feature-name

PR Template

## Description
Brief description of changes

## Related Issues
Fixes #123

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
How has this been tested?

## Checklist
- [ ] Tests pass locally
- [ ] Code follows project style
- [ ] Documentation updated
- [ ] Commit messages follow conventions

Code Style Guidelines

TypeScript

• Use TypeScript for all source code
• Enable strict mode
• Prefer const over let, avoid var
• Use descriptive type names
• Document public APIs with JSDoc comments

/**
 * Executes a Markdown code block as a task
 * @param cell - The code block to execute
 * @param context - Execution context
 * @returns Promise resolving to execution result
 */
export async function executeCell(
  cell: CodeCell,
  context: ExecutionContext
): Promise<ExecutionResult> {
  // Implementation
}

Markdown

• Use ATX-style headers (# syntax)
• Add blank lines around code blocks
• Use fenced code blocks with language identifiers
• Keep lines under 100 characters when possible
• Use reference-style links for readability

File Organization

Directory structure:

• lib/ - Core library code
  • core/ - Core functionality
  • parsers/ - Markdown parsers
  • executors/ - Code execution engines
  • sqlpage/ - SQLPage integration
• tests/ - Test files
• docs/ - Documentation
• examples/ - Example Spryfiles

Testing

Writing Tests

• Write tests for all new features
• Use descriptive test names
• Follow the Arrange-Act-Assert pattern
• Test edge cases and error conditions

Deno.test("executeCell: handles SQL queries correctly", async () => {
  // Arrange
  const cell = createSQLCell("SELECT 1");
  const context = createTestContext();
  
  // Act
  const result = await executeCell(cell, context);
  
  // Assert
  assertEquals(result.success, true);
  assertEquals(result.output, "1");
});

Running Tests

# Run all tests
deno test

# Run specific test file
deno test tests/parser_test.ts

# Run tests with coverage
deno test --coverage=coverage

# Generate coverage report
deno coverage coverage

Documentation

Documentation Standards

• Write clear, concise documentation
• Include practical examples
• Keep the audience in mind (beginners vs advanced users)
• Update docs alongside code changes
• Use proper Markdown formatting

Documentation Types

1. API Documentation - JSDoc comments in code
2. User Guides - Step-by-step tutorials
3. Reference - Comprehensive feature documentation
4. Examples - Working Spryfile.md examples

Community Guidelines

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

• Be respectful and considerate
• Accept constructive criticism gracefully
• Focus on what's best for the community
• Show empathy towards other community members

Communication

• Use GitHub Issues for bug reports and feature requests
• Use GitHub Discussions for questions and ideas
• Join Discord for real-time chat
• Be patient - maintainers are often volunteers

Review Process

Questions?