Contributing to FAF

First off, thank you for considering contributing to FAF! 🎉

FAF is built by the community, for the community. Whether you're fixing a bug, adding a new platform integration, improving documentation, or proposing a new feature, your contributions are welcome.

📋 Table of Contents

Code of Conduct
Getting Started
Development Setup
Project Structure
How to Contribute
Coding Standards
Testing Guidelines
Pull Request Process
Release Process

📖 Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to conduct@faf.dev.

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+ (Download)
npm or pnpm (comes with Node.js)
Chrome/Chromium browser for testing the extension
Git for version control

Development Setup

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/faf-production.git
cd faf-production

Add the original repository as upstream:

git remote add upstream https://github.com/Wolfe-Jam/faf-production.git

Install dependencies:
```
npm install
```
Start development mode:
```
npm run dev
```
Load the extension in Chrome:
- Navigate to chrome://extensions/
- Enable "Developer mode"
- Click "Load unpacked" and select the dist/ directory

🏗️ Project Structure

Understanding the codebase structure will help you navigate and contribute effectively:

faf-production/
├── src/
│   ├── core/                 # Core FAF engine
│   │   ├── engine.ts        # Main extraction engine
│   │   ├── types.ts         # TypeScript type definitions
│   │   ├── errors.ts        # Error handling and recovery
│   │   ├── scoring.ts       # Context quality scoring
│   │   └── telemetry.ts     # Anonymous usage analytics
│   ├── adapters/            # Platform-specific integrations
│   │   ├── chrome.ts        # Chrome extension APIs
│   │   ├── clipboard.ts     # Clipboard operations
│   │   └── platforms/       # Platform detection and extraction
│   ├── ui/                  # User interface components
│   │   ├── popup.svelte     # Extension popup interface
│   │   └── content.ts       # Content script for page interaction
│   └── background/          # Service worker
├── public/                  # Extension assets
│   ├── manifest.json        # Chrome extension manifest
│   └── icons/              # Extension icons
├── tests/                   # Test suites
└── dist/                   # Built extension files (generated)

🤝 How to Contribute

🐛 Reporting Bugs

Found a bug? Please help us fix it:

Check existing issues first to avoid duplicates
Use the bug report template when creating a new issue
Provide detailed steps to reproduce the problem
Include your environment details (OS, Chrome version, etc.)

💡 Suggesting Features

Have an idea for a new feature?

Check existing discussions and issues first
Use the feature request template
Explain the use case and why it would benefit users
Be open to discussion and alternative approaches

🔧 Code Contributions

Ready to write some code? Here are some great ways to contribute:

🟢 Good First Issues

Look for issues labeled good first issue - these are specifically chosen to be approachable for new contributors.

🔍 Platform Support

Add support for new development platforms:

Create a new platform adapter in src/adapters/platforms/
Implement the PlatformAdapter interface
Add comprehensive tests for the new platform
Update documentation

⚡ Performance Improvements

Help make FAF even faster:

Optimize extraction algorithms
Reduce memory usage
Improve startup time
Add performance benchmarks

🧪 Testing

Improve test coverage and quality:

Add unit tests for new features
Create integration tests for platform adapters
Add end-to-end tests for the extension
Test edge cases and error conditions

📏 Coding Standards

TypeScript Guidelines

Use strict TypeScript - No any types without explicit justification
Prefer interfaces over types for object shapes
Use explicit return types for public methods
Document complex functions with JSDoc comments

// ✅ Good
interface ExtractionResult {
  readonly success: boolean;
  readonly faf?: FAFContent;
  readonly error?: string;
}

async function extractContext(): Promise<ExtractionResult> {
  // Implementation
}

// ❌ Avoid
function extractContext(): any {
  // Implementation
}

Code Style

We use ESLint and Prettier to enforce consistent code style:

# Check linting
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

Naming Conventions

Variables and functions: camelCase
Constants: UPPER_SNAKE_CASE
Classes and interfaces: PascalCase
Files: kebab-case.ts or PascalCase.ts for classes

Error Handling

Use the custom FAFError class for consistent error handling:

import { FAFError, FAFErrorCode } from '@/core/errors';

// ✅ Good
throw new FAFError(
  FAFErrorCode.PLATFORM_NOT_SUPPORTED,
  'GitHub private repositories require authentication',
  {
    context: { platform: 'github', url: window.location.href }
  }
);

// ❌ Avoid generic errors
throw new Error('Something went wrong');

🧪 Testing Guidelines

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Writing Tests

Unit tests: Test individual functions and classes in isolation
Integration tests: Test interactions between components
E2E tests: Test the complete user workflow

Example test structure:

import { describe, it, expect, beforeEach } from 'vitest';
import { FAFEngine } from '@/core/engine';

describe('FAFEngine', () => {
  let engine: FAFEngine;

  beforeEach(() => {
    engine = new FAFEngine();
  });

  it('should extract context from GitHub repository', async () => {
    // Setup test environment
    // Act
    // Assert
  });
});

📥 Pull Request Process

Before You Submit

Create a feature branch from main:

git checkout -b feature/your-feature-name

Make your changes following the coding standards
Add or update tests for your changes
Ensure all tests pass:
```
npm test
```
Lint your code:
```
npm run lint
```
Update documentation if needed

Pull Request Checklist

When you submit your PR, please ensure:

Clear title and description explaining what and why
Tests added/updated for new functionality
All tests are passing
Code follows our style guidelines
Documentation updated if needed
No breaking changes without discussion
Commit messages are descriptive

Commit Message Format

We use conventional commits for clear history:

type(scope): description

[optional body]

[optional footer]

Examples:

feat(platforms): add GitLab support
fix(clipboard): handle permission denied gracefully
docs(readme): update installation instructions

Review Process

Automated checks will run on your PR
Team members will review your code
Address feedback if any changes are requested
Once approved, your PR will be merged

🚀 Release Process

Releases are handled by the maintainers:

Version bump using semantic versioning
Changelog generation from commit messages
Build and test the release candidate
Create GitHub release with release notes
Deploy to Chrome Web Store (automated)

🏷️ Issue Labels

We use labels to organize and prioritize work:

good first issue - Perfect for new contributors
bug - Something isn't working correctly
enhancement - New feature or improvement
documentation - Documentation needs updating
platform - Platform-specific integration work
performance - Performance optimization
breaking-change - Changes that break existing API

💬 Community & Support

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and ideas
Discord (coming soon): Real-time community chat

🙏 Recognition

All contributors are recognized in our README and release notes. Your contributions, no matter how small, help make FAF better for everyone.

Thank you for contributing to FAF! 🚀

Together, we're building the future of AI context extraction.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History