Contributing Guide

Welcome Contributors!

Thank you for your interest in contributing to Polaris IDE! This guide will help you get started with contributing code, documentation, and bug reports.

Getting Started

Fork the repository

Visit github.com/code-with-antonio/polaris and click the “Fork” button.

Clone your fork

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

Set up development environment

Follow the Setup Guide to install dependencies and configure environment variables.

Create a feature branch

git checkout -b feature/your-feature-name

Use prefixes:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
refactor/ - Code refactoring
test/ - Test additions/changes

Code Standards

TypeScript Guidelines

Use strict TypeScript

Enable strict mode in tsconfig.json
Avoid any types - use unknown or proper types
Use type inference where possible
Define explicit return types for functions

// ❌ Bad
function getData(id: any) {
  return fetch(`/api/${id}`);
}

// ✅ Good
async function getData(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

Component patterns

Use functional components with TypeScript:

// ✅ Good
interface EditorProps {
  content: string;
  onChange: (value: string) => void;
  language?: string;
}

export function Editor({ content, onChange, language = "typescript" }: EditorProps) {
  // Component implementation
}

Convex operations

All database operations must:

Verify authentication first
Use proper indexes
Handle errors gracefully

export const getProject = query({
  args: { id: v.id("projects") },
  handler: async (ctx, args) => {
    // ✅ Always verify auth first
    const identity = await verifyAuth(ctx);
    
    const project = await ctx.db.get(args.id);
    if (!project) {
      throw new Error("Project not found");
    }
    
    // ✅ Check ownership
    if (project.ownerId !== identity.subject) {
      throw new Error("Unauthorized");
    }
    
    return project;
  }
});

Error handling

Use descriptive error messages
Log errors to Sentry in production
Show user-friendly messages in UI

try {
  await createProject(name);
} catch (error) {
  // ✅ User-friendly message
  toast.error("Failed to create project. Please try again.");
  
  // ✅ Detailed logging
  console.error("Project creation failed:", error);
  Sentry.captureException(error);
}

Code Style

Formatting
Naming
Imports
Comments

Use ESLint for code quality
2 spaces for indentation
Single quotes for strings
Semicolons required
Trailing commas in multiline

# Run linter
npm run lint

# Auto-fix issues
npm run lint -- --fix

Components: PascalCase (UserProfile.tsx)
Files: kebab-case (use-editor.ts)
Functions: camelCase (getUserById)
Constants: UPPER_SNAKE_CASE (MAX_FILE_SIZE)
Interfaces: PascalCase with I prefix optional (UserProfile or IUserProfile)

Group imports in this order:

// 1. External dependencies
import { useState } from "react";
import { motion } from "framer-motion";

// 2. Internal absolute imports
import { Button } from "@/components/ui/button";
import { useEditor } from "@/features/editor/hooks/use-editor";

// 3. Relative imports
import { EditorToolbar } from "./editor-toolbar";
import type { EditorProps } from "./types";

Write self-documenting code
Use comments for “why”, not “what”
Document complex algorithms
Add JSDoc for public APIs

/**
 * Generates AI code suggestions based on context.
 * Uses debouncing to avoid excessive API calls.
 * 
 * @param code - Current file content
 * @param cursor - Cursor position
 * @returns AI-generated suggestion or null
 */
async function getSuggestion(code: string, cursor: number): Promise<string | null> {
  // Use 300ms debounce to balance responsiveness and API costs
  await delay(300);
  // ...
}

Testing

Unit Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:ui

# Run with coverage
npm run test:coverage

All new features should include unit tests. Aim for >80% code coverage.

E2E Tests

# Run Playwright tests
npm run test:e2e

# Run with UI
npm run test:e2e:ui

Pull Request Process

Ensure code quality

Before submitting:

Linting
Type checking
Tests
Build

npm run lint

npx tsc --noEmit

npm test
npm run test:e2e

npm run build

Commit your changes

Use conventional commit messages:

# Format: type(scope): description

feat(editor): add syntax highlighting for Python
fix(auth): resolve token refresh issue
docs(readme): update installation instructions
refactor(files): simplify file tree rendering
test(projects): add tests for project creation

Types:

feat - New feature
fix - Bug fix
docs - Documentation
refactor - Code restructuring
test - Tests
chore - Maintenance

Push to your fork

git push origin feature/your-feature-name

Create Pull Request

Go to the original repository
Click “New Pull Request”
Select your fork and branch
Fill out the PR template:

## Description
Brief description of changes

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

## Testing
- [ ] Unit tests pass
- [ ] E2E tests pass
- [ ] Manual testing completed

## Screenshots (if applicable)

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings

Address review feedback

Respond to all comments
Make requested changes
Push updates to the same branch
Re-request review when ready

Development Workflow

Feature Development

# Create feature branch
git checkout -b feature/ai-autocomplete

# Start dev servers
npm run dev
npx convex dev
npm run dev:trigger

Common Contribution Areas

CodeMirror Extensions

Add new editor features:

Language support
Custom themes
Editor widgets
Keybindings

See Custom Extensions Guide

AI Features

Enhance AI capabilities:

New AI tools
Prompt improvements
Model integrations
Context optimization

UI Components

Improve user interface:

shadcn/ui components
Layouts and panels
Responsive design
Accessibility

Documentation

Help others learn:

Guides and tutorials
API documentation
Code examples
Video walkthroughs

Community Guidelines

Code of Conduct

Be respectful and inclusive
Welcome newcomers
Focus on constructive feedback
Report inappropriate behavior

Getting Help

Check existing issues first
Use GitHub Discussions for questions
Join the Discord community
Tag maintainers when needed

Issue Reporting

When reporting bugs:

Search existing issues
Use the bug report template
Include reproduction steps
Provide environment details
Add screenshots/videos if helpful

Recognition

Contributors are recognized in:

CONTRIBUTORS.md file
Release notes
GitHub contributor graph
Special mentions in announcements

First-time contributors receive a special welcome and guidance from maintainers!

Next Steps

Setup Guide

Set up your development environment

Architecture

Understand the system design

Custom Extensions

Build CodeMirror extensions

Background Jobs

Work with Trigger.dev tasks

Development

Deployment

Advanced

Welcome Contributors!

Getting Started

Code Standards

TypeScript Guidelines

Code Style

Testing

Unit Tests

E2E Tests

Pull Request Process

Development Workflow

Feature Development

Common Contribution Areas

CodeMirror Extensions

AI Features

UI Components

Documentation

Community Guidelines

Recognition

Next Steps

Setup Guide

Architecture

Custom Extensions

Background Jobs

Build docs developers (and LLMs) love

Development

Deployment

Advanced

​Welcome Contributors!

​Getting Started

​Code Standards

​TypeScript Guidelines

​Code Style

​Testing

​Unit Tests

​E2E Tests

​Pull Request Process

​Development Workflow

​Feature Development

​Common Contribution Areas

CodeMirror Extensions

AI Features

UI Components

Documentation

​Community Guidelines

​Recognition

​Next Steps

Setup Guide

Architecture

Custom Extensions

Background Jobs

Build docs developers (and LLMs) love

Welcome Contributors!

Getting Started

Code Standards

TypeScript Guidelines

Code Style

Testing

Unit Tests

E2E Tests

Pull Request Process

Development Workflow

Feature Development

Common Contribution Areas

Community Guidelines

Recognition

Next Steps