Contributing

Guidelines for contributing to Paragrafs

Welcome Contributors!

Contributions are welcome! We appreciate your interest in improving Paragrafs. Please make sure your contributions adhere to the coding standards and are accompanied by relevant tests.

Getting Started

Follow these steps to set up your development environment:

1. Fork the repository

   Fork the Paragrafs repository on GitHub to your account.

2. Install Bun

   Paragrafs uses Bun as its runtime and package manager. Install it if you haven’t already:

   curl -fsSL https://bun.sh/install | bash
   
3. Clone and install dependencies

   Clone your fork and install dependencies:

   git clone https://github.com/YOUR_USERNAME/paragrafs.git
   cd paragrafs
   bun install
   
4. Make your changes

   Create a new branch and make your changes:

   git checkout -b feature/your-feature-name
   

Development Workflow

Code Quality Checks

Before submitting your changes, ensure they meet our quality standards:

Linting

# Run Biome's formatter and linter
bun run lint

All three commands (lint, build, and test) should pass without errors before submitting a pull request.

Project Structure

Paragrafs uses a Bun-native toolchain:

tsdown

Official bundler for compiling TypeScript (configured in tsdown.config.ts)

Biome

Fast linter and formatter (configured in biome.json)

Bun Test

Built-in test runner with coverage support

ESM

Modern ES modules format for all output

Coding Standards

TypeScript

• Write type-safe code with proper TypeScript annotations
• Avoid any types when possible
• Use interfaces for public APIs
• Export types alongside implementations

Code Style

Formatting

Biome handles code formatting automatically. Run bun run lint to format your code.

Naming Conventions

• Use camelCase for functions and variables
• Use PascalCase for types and interfaces
• Use SCREAMING_SNAKE_CASE for constants
• Use descriptive names that explain intent

Documentation

• Add JSDoc comments for public APIs
• Include examples in complex functions
• Document parameters and return types
• Explain any non-obvious behavior

Testing Requirements

All new features and bug fixes must include relevant tests.

When writing tests:

• Cover both happy paths and edge cases
• Use descriptive test names that explain what’s being tested
• Aim for high code coverage (check with bun test --coverage)
• Test public APIs, not implementation details
• Include tests for Arabic text handling when relevant

Example Test

import { describe, expect, test } from 'bun:test';
import { createHints } from '../src/utils/textUtils';

describe('createHints', () => {
  test('should normalize Arabic text by default', () => {
    const hints = createHints('مرحباً');
    expect(hints).toBeDefined();
    // Add assertions for normalized behavior
  });
});

Submitting Changes

1. Run all quality checks

   Before submitting, ensure all checks pass:

   bun run lint && bun run build && bun test --coverage
   
2. Commit your changes

   Write clear, descriptive commit messages:

   git add .
   git commit -m "feat: add support for custom hint normalization"
   
3. Push to your fork

   git push origin feature/your-feature-name
   
4. Submit a pull request

   Open a pull request on GitHub with:

   • Clear description of the changes
   • Reference to any related issues
   • Screenshots or examples if applicable
   • Confirmation that tests pass

Demo App Development

Paragrafs includes a Svelte + Vite demo app in the demo/ directory:

Demo Commands

# Install demo dependencies
bun run demo:install

# Run development server
bun run demo:dev

# Build demo app
bun run demo:build

# Deploy to Surge
bun run demo:deploy

The demo depends on the local package via file:.., so demo:build automatically runs bun run build first.

Contribution Ideas

Looking for ways to contribute? Here are some ideas:

Bug Fixes

Check the issues page for reported bugs

Documentation

Improve examples, add tutorials, or clarify existing docs

Performance

Optimize algorithms for better performance

Features

Propose new features that enhance transcription processing

Tests

Increase test coverage or add edge case testing

Language Support

Enhance support for languages beyond Arabic

Code Review Process

After submitting a pull request:

1. Automated checks will run (CI build, tests, linting)
2. Maintainer review - a project maintainer will review your code
3. Feedback - you may receive requests for changes
4. Approval - once approved, your PR will be merged
5. Release - your changes will be included in the next release

Be responsive to feedback and questions during code review. It helps get your contribution merged faster!

Community Guidelines

• Be respectful and constructive in discussions
• Follow the code of conduct (if available)
• Help other contributors when possible
• Ask questions if something is unclear

License

By contributing to Paragrafs, you agree that your contributions will be licensed under the MIT License.

Questions?

Open an Issue

Have questions about contributing? Open an issue and we’ll help you get started!