title	Contributing to 3Lens
description	Guidelines and information for contributing to 3Lens

Contributing to 3Lens

Thank you for your interest in contributing to 3Lens! This document provides guidelines and information for contributors.

Code of Conduct
Getting Started
Development Setup
Project Structure
Development Workflow
Coding Standards
Testing
Documentation
Pull Request Process
Release Process

Code of Conduct

This project follows a standard code of conduct. Please be respectful and constructive in all interactions.

Our Standards

Be welcoming and inclusive
Be respectful of differing viewpoints
Accept constructive criticism gracefully
Focus on what is best for the community

Getting Started

Ways to Contribute

Bug Reports: Found a bug? Open an issue with steps to reproduce
Feature Requests: Have an idea? Open a discussion or issue
Code Contributions: Submit PRs for bugs, features, or docs
Documentation: Improve docs, add examples, fix typos
Testing: Help test pre-releases and report issues
Community: Answer questions, help other users

First-Time Contributors

Look for issues labeled:

good first issue - Simple, well-defined issues
help wanted - Issues where we need community help
documentation - Documentation improvements

Development Setup

Prerequisites

Node.js: v18.0.0 or later
pnpm: v8.0.0 or later
Git: Latest version
Browser: Chrome and Firefox for testing

Installation

# Clone the repository
git clone https://github.com/your-org/3lens.git
cd 3lens

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

Development Mode

# Start development watchers for all packages
pnpm dev

# Start specific package in dev mode
pnpm --filter @3lens/core dev
pnpm --filter @3lens/overlay dev

Running the Extension

# Build extension
pnpm --filter @3lens/extension build

# Load in Chrome:
# 1. Go to chrome://extensions/
# 2. Enable "Developer mode"
# 3. Click "Load unpacked"
# 4. Select packages/extension/dist

Running Example Apps

# Start example app
pnpm --filter examples-basic dev

Project Structure

3lens/
├── docs/                    # Documentation
│
├── packages/
│   ├── core/               # @3lens/core - Probe SDK
│   │   ├── src/
│   │   │   ├── probe/      # DevtoolProbe class
│   │   │   ├── adapters/   # WebGL/WebGPU adapters
│   │   │   ├── observers/  # Scene, resource observers
│   │   │   ├── transport/  # Message transport
│   │   │   └── types/      # TypeScript types
│   │   ├── tests/
│   │   └── package.json
│   │
│   ├── overlay/            # @3lens/overlay - In-app UI
│   │   ├── src/
│   │   │   ├── components/ # UI components
│   │   │   ├── panels/     # Panel implementations
│   │   │   ├── stores/     # State management
│   │   │   └── mount.ts    # Entry point
│   │   └── package.json
│   │
│   ├── extension/          # Browser extension
│   │   ├── src/
│   │   │   ├── devtools/   # DevTools panel
│   │   │   ├── content/    # Content script
│   │   │   └── background/ # Service worker
│   │   ├── manifest.json
│   │   └── package.json
│   │
│   ├── react-bridge/       # @3lens/react-bridge
│   ├── angular-bridge/     # @3lens/angular-bridge
│   ├── vue-bridge/         # @3lens/vue-bridge
│   │
│   └── shared/             # Shared utilities
│       ├── protocol/       # Debug protocol types
│       └── ui-components/  # Shared UI components
│
├── examples/               # Example applications
│   ├── basic/             # Vanilla three.js
│   ├── react-r3f/         # React Three Fiber
│   └── angular/           # Angular + three.js
│
├── scripts/               # Build/release scripts
├── pnpm-workspace.yaml
└── package.json

Development Workflow

Branching Strategy

main - Stable, release-ready code
develop - Integration branch for features
feature/* - Feature branches
fix/* - Bug fix branches
docs/* - Documentation changes

Typical Workflow

Create a branch

git checkout -b feature/my-feature develop

Make changes
- Write code
- Add tests
- Update documentation

Commit with conventional commits

git commit -m "feat(core): add GPU timing support"

Push and create PR
```
git push origin feature/my-feature
```
Address review feedback
Merge after approval

Commit Message Format

We use Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

feat - New feature
fix - Bug fix
docs - Documentation
style - Formatting (no code change)
refactor - Code restructuring
perf - Performance improvement
test - Adding tests
chore - Build/tooling changes

Scopes:

core - @3lens/core
overlay - @3lens/overlay
extension - Browser extension
react - React bridge
angular - Angular bridge
vue - Vue bridge
docs - Documentation
build - Build system

Examples:

feat(core): add WebGPU adapter
fix(overlay): fix panel resize on Firefox
docs: update installation guide
perf(core): reduce frame stats overhead

Coding Standards

TypeScript

Strict mode enabled
Explicit return types on public functions
Prefer interface over type for object shapes
Use readonly where appropriate

// ✅ Good
interface ProbeConfig {
  readonly appName: string;
  rules?: RulesConfig;
}

function createProbe(config: ProbeConfig): DevtoolProbe {
  // ...
}

// ❌ Avoid
type ProbeConfig = {
  appName: string;
  rules?: any;
};

Code Style

Prettier for formatting
ESLint for linting
2-space indentation
Single quotes
No semicolons (configurable)
Max line length: 100

# Format code
pnpm format

# Lint code
pnpm lint

# Fix lint issues
pnpm lint:fix

Naming Conventions

Type	Convention	Example
Files	kebab-case	`scene-observer.ts`
Classes	PascalCase	`SceneObserver`
Interfaces	PascalCase, no `I` prefix	`ProbeConfig`
Functions	camelCase	`createProbe`
Constants	SCREAMING_SNAKE_CASE	`MAX_FRAME_HISTORY`
Private properties	underscore prefix	`_isConnected`

File Organization

// 1. Imports (external, then internal)
import * as THREE from 'three';
import { Transport } from '../transport';

// 2. Types/Interfaces
interface ObserverOptions {
  // ...
}

// 3. Constants
const DEFAULT_OPTIONS: ObserverOptions = {};

// 4. Class/Function implementation
export class SceneObserver {
  // ...
}

// 5. Exports (if not inline)

Testing

Test Structure

packages/core/
├── src/
│   └── probe/
│       └── probe.ts
└── tests/
    └── probe/
        ├── probe.test.ts       # Unit tests
        └── probe.integration.ts # Integration tests

Running Tests

# Run all tests
pnpm test

# Run tests for specific package
pnpm --filter @3lens/core test

# Run tests in watch mode
pnpm test:watch

# Run with coverage
pnpm test:coverage

Writing Tests

Use Vitest for testing:

import { describe, it, expect, vi } from 'vitest';
import { createProbe } from '../src';

describe('createProbe', () => {
  it('should create a probe with default config', () => {
    const probe = createProbe({ appName: 'TestApp' });
    
    expect(probe).toBeDefined();
    expect(probe.config.appName).toBe('TestApp');
  });

  it('should observe a renderer', () => {
    const probe = createProbe({ appName: 'TestApp' });
    const mockRenderer = createMockRenderer();
    
    expect(() => probe.observeRenderer(mockRenderer)).not.toThrow();
  });
});

Test Coverage Requirements

Package	Minimum Coverage
`@3lens/core`	80%
`@3lens/overlay`	70%
`@3lens/extension`	60%
Bridge packages	70%

Documentation

Documentation Types

API Reference - Generated from TSDoc comments
Guides - How-to articles in /docs
Examples - Code examples in /examples

TSDoc Comments

/**
 * Creates a new DevtoolProbe instance.
 * 
 * @param config - Probe configuration options
 * @returns A new DevtoolProbe instance
 * 
 * @example
 * ```typescript
 * const probe = createProbe({
 *   appName: 'My App',
 *   rules: { maxDrawCalls: 1000 }
 * });
 * ```
 * 
 * @see {@link DevtoolProbe}
 * @public
 */
export function createProbe(config: ProbeConfig): DevtoolProbe {
  // ...
}

Documentation Updates

Update docs when changing public APIs
Add examples for new features
Keep README.md in sync with changes

Pull Request Process

Before Submitting

PR Template

## Description
Brief description of changes

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

## Testing
How was this tested?

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

Review Process

Automated checks - CI must pass
Code review - At least one approval required
Testing - Manual testing for UI changes
Documentation review - For public API changes

Merge Requirements

All checks pass
At least one approval
No unresolved conversations
Branch up to date with target

Release Process

Version Bumping

We use changesets for version management:

# Add a changeset for your PR
pnpm changeset

# Follow the prompts to describe your change

Release Workflow

Changesets accumulate in .changeset/
Maintainers run pnpm changeset version
Version bumps and CHANGELOG updates
Tag and publish to npm

Release Channels

Channel	Command	Description
Alpha	`pnpm release:alpha`	Pre-release for testing
Beta	`pnpm release:beta`	Feature-complete pre-release
Latest	`pnpm release`	Stable release

Getting Help

Discord: Join our community (link TBD)
GitHub Discussions: For questions and ideas
GitHub Issues: For bugs and feature requests

Maintainers

@adriandarian - Core SDK & UI/UX

License

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

Thank you for contributing to 3Lens! 🎉

Uh oh!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History