Contributing Guidelines

​

Ways to Contribute

• Bug fixes: Fix issues reported in GitHub Issues
• Features: Add new visualization types, UI improvements, or backend capabilities
• Documentation: Improve setup guides, API docs, or authoring references
• Courses: Create new programming courses using the Handhold DSL
• Testing: Write tests for existing functionality
• Performance: Optimize parsing, rendering, or build times

​

Getting Started

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

git checkout -b feature/your-feature-name

bun tauri dev

git commit -m "feat: add stack visualization primitive"
git commit -m "fix: prevent crash when lesson has no steps"
git commit -m "docs: add parser architecture diagram"

git push origin feature/your-feature-name

​

Pull Request Guidelines

​

PR Title

feat: add stack visualization primitive
fix: prevent crash when lesson has no steps
docs: add parser architecture diagram

​

PR Description

1. What changed: Brief summary of the changes
2. Why: The motivation or problem being solved
3. How: High-level explanation of the approach
4. Testing: How you verified the changes work
5. Screenshots: If UI changes, include before/after screenshots

## What
Adds a new `stack` visualization type to the data primitive.

## Why
Many algorithms use stacks, but the current data visualizations only support arrays and linked lists.

## How
- Added `StackLayout` component in `src/data/layouts/`
- Extended parser to recognize `stack` type in data blocks
- Added animation support for push/pop operations

## Testing
- Created a test lesson with stack operations
- Verified animations play correctly
- Tested with empty stack edge case

## Screenshots
[Include screenshot of stack visualization]

​

Code Review Process

1. Maintainers will review your PR within a few days
2. Address feedback by pushing new commits
3. Once approved, a maintainer will merge your PR

​

Code Style

​

TypeScript/React

• Use TypeScript strict mode (enabled by default)
• Prefer functional components and hooks
• Use readonly for props and immutable data
• Avoid any types; use unknown or explicit types
• Run Prettier before committing (not yet configured, but recommended)

type Props = {
  readonly title: string;
  readonly onComplete: () => void;
};

export function Component({ title, onComplete }: Props) {
  // ...
}

​

Rust

• Follow Rust standard style (cargo fmt)
• Use descriptive variable names
• Prefer Result<T, E> over panics for recoverable errors
• Document public APIs with /// doc comments

/// Reads a file from the filesystem and returns its contents.
///
/// # Errors
/// Returns an error if the file does not exist or cannot be read.
#[tauri::command]
pub fn read_file(path: String) -> Result<String, String> {
    std::fs::read_to_string(path)
        .map_err(|e| e.to_string())
}

​

Testing

• Parser tests: Verify markdown parsing produces correct IR
• Trigger tests: Ensure trigger syntax is parsed correctly
• Data layout tests: Validate layout algorithms
• Backend tests: Test Tauri commands in isolation

​

Documentation

• README.md: User-facing setup and installation
• docs/authoring-guide.md: Course authoring reference
• This docs site: Development guides (you’re reading one!)

​

Creating Courses

1. Write the course as a markdown file using the authoring DSL
2. Test it in Handhold to ensure all triggers and visualizations work
3. Submit the course as a separate repository or open an issue to discuss inclusion

​

Reporting Bugs

1. Check if it’s already reported in GitHub Issues
2. If not, open a new issue with:
   • Title: Short description of the bug
   • Description: Steps to reproduce, expected behavior, actual behavior
   • Environment: OS, Handhold version, relevant setup details
   • Screenshots/logs: If applicable

**Bug**: App crashes when opening a lesson with no narration blocks

**Steps to reproduce**:
1. Create a lesson with only visualization blocks
2. Open the lesson in Handhold
3. Click play

**Expected**: App plays the lesson or shows an error
**Actual**: App crashes with SIGSEGV

**Environment**: macOS 14.3, Handhold v0.2.11

​

Requesting Features

1. Open a GitHub Issue with the enhancement label
2. Describe the feature and why it’s useful
3. Provide examples or mockups if applicable

**Feature**: Add support for custom color themes

**Why**: Users want to customize the appearance of code blocks and diagrams to match their preferred color scheme.

**Details**:
- Allow users to define color palettes in settings
- Apply palettes to syntax highlighting, diagrams, and UI elements
- Provide a few built-in themes (dark, light, high contrast)

​

License

​

Code of Conduct

• Be patient with questions from newcomers
• Provide constructive feedback during code review
• Respect differing viewpoints and experiences
• Accept responsibility and apologize for mistakes

​

Contact

• GitHub Issues: For bug reports and feature requests
• GitHub Discussions: For general questions and ideas (if enabled)
• Email: Reach out to the maintainer at [email protected]

​

Recognition

• GitHub’s contributor graph
• Release notes for significant features

​

Next Steps