Contributing to SnapBack

We welcome contributions from the community! SnapBack has multiple open-source repositories where you can contribute.

Where to Contribute

SnapBack has several public repositories under the snapback-dev organization:

User-Facing Applications

VS Code Extension

• Primary user interface for SnapBack
• File protection and snapshot management UI
• Issue tracker for user-reported bugs
• Best for: UI improvements, extension features, bug fixes

MCP Server

• Model Context Protocol integration
• AI assistant code safety integration
• Best for: AI integration features, MCP protocol improvements

Open Source Packages

@snapback-oss/sdk

• Core snapshot management SDK
• Storage adapters and file operations
• Best for: Core functionality, storage improvements, API enhancements

@snapback-oss/contracts

• TypeScript type definitions
• Event schemas and API contracts
• Best for: Type safety improvements, schema definitions

@snapback-oss/config

• Configuration management utilities
• .snapbackrc parsing and validation
• Best for: Configuration features, validation logic

@snapback-oss/events

• Event bus implementation
• Pub/sub patterns for snapshot events
• Best for: Event system improvements, new event types

@snapback-oss/infrastructure

• Logging and metrics utilities
• Generic infrastructure helpers
• Best for: Logging improvements, utility functions

Getting Started

Prerequisites

• Node.js 20+ (Download)
• pnpm 9+ (npm install -g pnpm)
• Git

Contributing to a Package

Each repository has its own setup process. Here’s the general workflow:

Copy# 1. Fork the repository on GitHub
# Click "Fork" on the repo you want to contribute to

# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/REPO_NAME.git
cd REPO_NAME

# 3. Install dependencies
pnpm install

# 4. Build the package
pnpm build

# 5. Run tests
pnpm test

# 6. Start development
pnpm dev

Contributing to VS Code Extension

Copy# 1. Fork https://github.com/snapback-dev/vscode
git clone https://github.com/YOUR_USERNAME/vscode.git
cd vscode

# 2. Install dependencies
pnpm install

# 3. Open in VS Code
code .

# 4. Press F5 to launch Extension Development Host
# This opens a new VS Code window with your extension loaded

# 5. Make changes and test in the development window

# 6. Run tests
pnpm test

Package Architecture

Each OSS package follows a consistent structure:

Copypackage-name/
├── src/                       # Source code
│   ├── index.ts              # Main entry point
│   ├── types.ts              # Type definitions
│   └── utils/                # Utility functions
├── tests/                    # Test files
│   ├── unit/                 # Unit tests
│   └── integration/          # Integration tests
├── package.json              # Package configuration
├── tsconfig.json             # TypeScript config
├── README.md                 # Package documentation
└── CONTRIBUTING.md           # Contribution guidelines

Package Naming Convention

• Public packages: @snapback-oss/* (e.g., @snapback-oss/sdk, @snapback-oss/contracts)
• Published to npm and available for community use

Key Packages

SDK Package (@snapback-oss/sdk)

Purpose: Core snapshot management and file protection

Key APIs:

• SnapshotManager - Create and restore snapshots
• ProtectionEngine - File protection rules
• RiskAnalyzer - Security risk detection

Contribution areas:

• Storage adapter improvements
• New snapshot features
• Performance optimizations
• Bug fixes

View SDK repository →

Contracts Package (@snapback-oss/contracts)

Purpose: TypeScript types and event schemas

Key exports:

• Type definitions for snapshots, events, and configs
• Event schemas for pub/sub
• API contracts

Contribution areas:

• Type safety improvements
• New event definitions
• Schema validation
• Documentation improvements

View contracts repository →

Config Package (@snapback-oss/config)

Purpose: Configuration management

Key APIs:

• .snapbackrc parsing
• Configuration validation
• Default config generation

Contribution areas:

• New configuration options
• Validation logic
• Config migration tools
• Documentation

View config repository →

Events Package (@snapback-oss/events)

Purpose: Event bus for snapshot lifecycle

Key APIs:

• Event emitter/subscriber
• Event filtering
• Type-safe event handlers

Contribution areas:

• New event types
• Event filtering improvements
• Performance optimizations
• Testing utilities

View events repository →

Infrastructure Package (@snapback-oss/infrastructure)

Purpose: Generic utilities and helpers

Key exports:

• Logging utilities
• Metrics helpers
• Generic type utilities

Contribution areas:

• Utility functions
• Logging improvements
• Testing helpers
• Documentation

View infrastructure repository →

Development Workflow

1. Creating a Feature

Copy# Create feature branch from main
git checkout -b feature/my-feature

# Make your changes
# Follow the code style guidelines below

# Run tests
pnpm test

# Type check
pnpm type-check

# Lint
pnpm lint

2. Package-Specific Development

Each repository has its own development commands. Common patterns:

Copy# Watch mode for development
pnpm dev

# Run specific tests
pnpm test:unit
pnpm test:integration

# Build for production
pnpm build

# Check types
pnpm type-check

Check each repository’s README for specific commands.

3. Committing Changes

We use conventional commits:

Copygit commit -m "feat(sdk): add snapshot validation"
git commit -m "fix(infrastructure): improve logger performance"
git commit -m "docs(contracts): update type definitions"

Commit types: feat, fix, docs, style, refactor, test, chore

4. Submitting a Pull Request

1. Push your branch to your fork
2. Open a PR against the main repository on GitHub
3. Fill out the PR template with:
   • Description of changes
   • Related issues (if any)
   • Testing performed
4. Ensure CI passes: Tests, linting, type checking
5. Address review feedback promptly
6. Maintainers will merge once approved

PR Tips:

• Keep PRs focused and small when possible
• Write clear commit messages
• Update documentation if needed
• Add tests for new features

Code Style Guidelines

TypeScript

We follow strict TypeScript patterns:

• Discriminated Unions: Use for state machines and result types
• Type Guards: Use is predicates for type narrowing
• Const Assertions: Use as const for readonly data
• Result Types: Use Result<T, E> pattern for error handling

Example:

Copy// ✅ Discriminated union for state
type SnapshotState =
  | { status: "loading" }
  | { status: "ready"; data: Snapshot }
  | { status: "error"; error: Error };

// ✅ Type guard
function isReady(state: SnapshotState): state is { status: "ready"; data: Snapshot } {
  return state.status === "ready";
}

// ✅ Result type for error handling
async function createSnapshot(path: string): Promise<Result<Snapshot, Error>> {
  try {
    const snapshot = await storage.create(path);
    return Ok(snapshot);
  } catch (err) {
    return Err(toError(err));
  }
}

Imports

Use package imports for cross-package dependencies:

Copy// ✅ CORRECT - Cross-package imports use @snapback/* namespace
import { logger } from "@snapback/infrastructure";
import type { Snapshot } from "@snapback/contracts";

// ❌ WRONG - Don't use relative paths across packages
import { logger } from "../../../packages/infrastructure/src/logging";

Comments

• English only for code comments
• Chinese allowed for business logic explanations
• Document public APIs with JSDoc
• Mark TODOs with issue numbers: // TODO: #123

Copy/**
 * Creates a snapshot of the specified file.
 *
 * @param filePath - Absolute file path
 * @returns Result containing snapshot or error
 *
 * @example
 * ```typescript
 * const result = await createSnapshot("/path/to/file.ts");
 * if (isOk(result)) {
 *   console.log("Snapshot created:", result.value.id);
 * }
 * ```
 */
async function createSnapshot(filePath: string): Promise<Result<Snapshot, Error>> {
  // Implementation
}

Contributing to OSS Packages

Only the following packages are public open-source:

• @snapback-oss/contracts
• @snapback-oss/sdk
• @snapback-oss/infrastructure
• @snapback-oss/config
• @snapback-oss/events

Rules for OSS Packages

Never add:

• Database schemas or migrations
• Proprietary algorithms
• Analytics or telemetry code (use @snapback-oss/infrastructure for logging only)
• Subscription/tier logic
• Internal platform code
• Hardcoded API keys or secrets

Always ensure:

• No imports from private packages (@snapback/core, @snapback-oss/* cannot import @snapback/*)
• Dependencies are safe for public consumption
• Types don’t expose private implementation details
• Tests pass with public dependencies only

Testing OSS Packages

Copy# Test all OSS packages
pnpm --filter "@snapback-oss/*" test

# Build all OSS packages
pnpm --filter "@snapback-oss/*" build

# Type check
pnpm --filter "@snapback-oss/*" type-check

Testing

Writing Tests

Tests use Vitest for unit tests and integration tests.

Copyimport { describe, it, expect } from "vitest";
import { createSnapshot } from "@snapback/sdk";

describe("Snapshot Creation", () => {
  it("should create a snapshot successfully", async () => {
    const result = await createSnapshot("/path/to/file.ts");

    expect(isOk(result)).toBe(true);
    if (isOk(result)) {
      expect(result.value).toHaveProperty("id");
      expect(result.value).toHaveProperty("timestamp");
    }
  });

  it("should return error for invalid path", async () => {
    const result = await createSnapshot("");

    expect(isErr(result)).toBe(true);
    if (isErr(result)) {
      expect(result.error).toBeInstanceOf(Error);
    }
  });
});

Running Tests

Copy# Run all tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Run tests for a specific package
pnpm -F @snapback/sdk test

# Run tests with coverage
pnpm test --coverage

Building and Publishing

Local Testing

Copy# Build all packages
pnpm build

# Build a specific package
pnpm -F @snapback/sdk build

# Verify build output
ls packages/sdk/dist

Publishing (Maintainers Only)

Copy# Update version
pnpm version

# Publish to npm
pnpm publish

Reporting Issues

Found a bug? We appreciate detailed bug reports:

1. Search existing issues to avoid duplicates
2. Provide a minimal reproduction (code snippet or test case)
3. Include environment (Node.js version, OS, etc.)
4. Describe expected vs actual behavior

Bug Report Template

Copy**Environment:**
- OS: [e.g., macOS 15.0]
- Node.js: [e.g., 20.10]
- pnpm: [e.g., 9.1]

**Steps to reproduce:**
1.
2.
3.

**Expected behavior:**
What should happen?

**Actual behavior:**
What actually happens?

**Error message:**
(Include full error stack if available)

Requesting Features

Have an idea? We’d love to hear it!

1. Check discussions for similar ideas
2. Create a discussion with your use case
3. Describe the problem you’re trying to solve
4. Suggest a solution (optional)

Recognition

Contributors are recognized in:

• GitHub contributor graph
• Release notes (for significant contributions)
• Contributors page (coming soon)

Getting Help

Documentation

• API Reference: CLI Reference
• Examples: Check each repository’s examples/ directory
• Tests: Look at tests/ directories for usage examples

Community

• GitHub Issues: Report bugs and request features
• GitHub Discussions: Ask questions and share ideas
• Discord: Join our community

Repository-Specific Help

Each repository has its own:

• CONTRIBUTING.md - Contribution guidelines
• README.md - Setup and usage instructions
• Issue templates - For bug reports and feature requests

Recognition

We value your contributions! Contributors are recognized through:

• Git commit history
• Release notes (for significant contributions)
• Community shoutouts in Discord
• Pioneer Program points (if enrolled)

License

By contributing to SnapBack, you agree that your contributions will be licensed under the same license as the respective project:

• Most packages: Apache 2.0 (see LICENSE in each repo)
• VS Code Extension: Check repository for license

---

Have questions? Create a discussion on GitHub or reach out in Discord!