Contributing to Voiden SDK

February 22, 2026 · View on GitHub

Thank you for your interest in contributing to the Voiden SDK! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Getting Started

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/YOUR-USERNAME/sdk.git
  3. Add upstream remote: git remote add upstream https://github.com/VoidenHQ/sdk.git
  4. Create a new branch: git checkout -b feature/your-feature-name

Development Setup

Prerequisites

  • Node.js 20.x or higher
  • npm or yarn
  • TypeScript knowledge

Installation

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run dev

# Run type checking
npm run typecheck

Note: This project commits package-lock.json for reproducible builds. Always use npm install (not npm update) unless you're intentionally updating dependencies.

How to Contribute

Types of Contributions

We welcome various types of contributions:

  • Bug fixes - Fix issues in existing code
  • New features - Add new extension APIs or capabilities
  • Documentation - Improve README, add examples, write guides
  • Examples - Create example extensions demonstrating SDK features
  • Tests - Add or improve test coverage

Before You Start

  1. Check if an issue already exists for what you want to work on
  2. For major changes, open an issue first to discuss your proposal
  3. For bug fixes, search existing issues or create a new one
  4. Comment on the issue to let others know you're working on it

Pull Request Process

  1. Update your fork with the latest changes from upstream:

    git fetch upstream
git rebase upstream/main

  2. Make your changes following the coding guidelines below

  3. Test your changes:

    npm run build
npm run typecheck

  4. Commit your changes with clear, descriptive commit messages:

    git commit -m "feat: add new API for custom panels"

    Follow Conventional Commits format:

    • feat: - New features
    • fix: - Bug fixes
    • docs: - Documentation changes
    • chore: - Maintenance tasks
    • refactor: - Code refactoring
    • test: - Adding or updating tests

  5. Push to your fork:

    git push origin feature/your-feature-name

  6. Create a Pull Request from your fork to the main repository

  7. Address review feedback - Be responsive to comments and requested changes

Pull Request Guidelines

  • Keep PRs focused on a single feature or bug fix
  • Include a clear description of what the PR does
  • Reference any related issues (e.g., "Fixes #123")
  • Update documentation if you're changing APIs
  • Add examples if introducing new features
  • Ensure all checks pass before requesting review

Coding Guidelines

TypeScript Style

  • Use TypeScript strict mode
  • Provide explicit type annotations for public APIs
  • Use interfaces for public types
  • Document all public APIs with JSDoc comments
  • Prefer const over let, avoid var
  • Use meaningful variable and function names

Code Organization

  • Keep files focused on a single responsibility
  • Export only what's necessary for the public API
  • Group related functionality together
  • Maintain consistent file structure

Documentation

  • Add JSDoc comments to all public classes, methods, and types
  • Include @example tags showing usage
  • Document parameters with @param and return values with @returns
  • Keep comments up-to-date when changing code

Example

/**
 * Registers a custom block in the editor
 *
 * @param block - The block definition
 * @example
 * ```ts
 * this.registerBlock({
 *   name: 'my-block',
 *   label: 'My Block',
 *   node: MyBlockNode,
 * });
 * ```
 */
registerBlock(block: BlockDefinition): void {
  // Implementation
}

Reporting Bugs

When reporting bugs, include:

  • Description - Clear description of the bug
  • Steps to reproduce - Minimal steps to reproduce the issue
  • Expected behavior - What you expected to happen
  • Actual behavior - What actually happened
  • Environment - OS, Node.js version, SDK version
  • Code sample - Minimal reproducible example
  • Screenshots - If applicable

Use the bug report template when creating issues.

Suggesting Enhancements

For feature requests:

  • Use case - Describe the problem you're trying to solve
  • Proposed solution - Your suggested approach
  • Alternatives - Other solutions you've considered
  • Examples - Code examples showing how it would work

Continuous Integration

This project uses GitHub Actions for continuous integration and deployment:

CI Workflow

Every push to main and all pull requests trigger the CI workflow that:

  • Runs on Node.js 20.x and 22.x
  • Installs dependencies
  • Runs type checking (npm run typecheck)
  • Runs tests (npm test)
  • Builds the project (npm run build)

All checks must pass before a PR can be merged.

Publishing Workflow

When a new release is published on GitHub:

  1. The publish workflow automatically triggers
  2. Runs all CI checks (tests, type check, build)
  3. Publishes the package to npm with provenance

Creating a Release

To publish a new version:

  1. Update the version in package.json following Semantic Versioning
  2. Update CHANGELOG.md with the new version and changes
  3. Commit the changes: git commit -m "chore: release v1.x.x"
  4. Create a git tag: git tag v1.x.x
  5. Push with tags: git push && git push --tags
  6. Create a GitHub release from the tag
  7. The GitHub Action will automatically publish to npm

Note: Publishing uses npm Trusted Publishing (OIDC) — no NPM_TOKEN secret is required. The publish job runs in the release GitHub Actions environment, which must be configured in the repository settings to match the npm Trusted Publisher configuration.

Questions?

If you have questions:

License

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