Contribution Guide

We welcome contributions to ThinkCode! This guide will help you set up your development environment, understand our coding standards, and navigate the contribution process.

Getting Started

Contributing to ThinkCode can be a rewarding experience. Whether you're fixing bugs, adding features, improving documentation, or extending functionality, your contributions help make ThinkCode better for everyone.

Types of Contributions

There are many ways to contribute to ThinkCode:

• Code contributions: Bug fixes, feature implementations, performance improvements
• Documentation: Improving guides, examples, and API documentation
• Testing: Writing tests, testing on different platforms, test automation
• Design: UI/UX improvements, accessibility enhancements
• Translations: Helping make ThinkCode available in more languages
• Bug reports: Identifying and reporting issues
• Feature requests: Suggesting new features or enhancements

Setting Up the Development Environment

Follow these steps to set up your development environment for ThinkCode:

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: v18.x or higher (LTS recommended)
• pnpm: v8.x or higher
• Git: Recent version
• Visual Studio Code: Latest stable version (recommended)
• Python: v3.10 or higher (for certain components)

Cloning the Repository

1. Fork the ThinkCode repository on GitHub
2. Clone your fork locally:

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

3. Add the upstream repository as a remote:

git remote add upstream https://github.com/thinkcode-dev/thinkcode.git

Installing Dependencies

ThinkCode uses pnpm workspaces to manage its monorepo structure:

# Install dependencies for all packages
pnpm install
 
# Build all packages
pnpm build

Setting Up Local AI Services

For developing AI-related features, you'll need to set up local AI services:

1. Create a .env.local file in the root directory with the following variables:

THINKCODE_AI_SERVICE_URL=http://localhost:3030
THINKCODE_AI_SERVICE_API_KEY=dev-key

2. Start the local AI service:

pnpm run ai:service:dev

Running ThinkCode for Development

To start ThinkCode in development mode:

# Start the development server for the web app
pnpm dev
 
# Start the desktop app in development mode
pnpm electron:dev

Extension Development

To develop a ThinkCode extension:

# Create a new extension from template
pnpm create-extension my-extension
 
# Start the extension development server
cd extensions/my-extension
pnpm dev

Project Structure

Understanding the project structure will help you navigate the codebase:

thinkcode/
├── apps/                   # Applications
│   ├── desktop/            # Electron desktop app
│   ├── web/                # Web application
│   └── vscode/             # VSCode integration
├── packages/               # Core packages
│   ├── ai/                 # AI integration
│   ├── api/                # API layer
│   ├── core/               # Core functionality
│   ├── ui/                 # UI components
│   └── utils/              # Shared utilities
├── extensions/             # Extensions
│   ├── core-extensions/    # Official extensions
│   └── templates/          # Extension templates
├── scripts/                # Build and development scripts
├── docs/                   # Documentation source
└── tests/                  # Integration tests

Coding Standards

ThinkCode follows strict coding standards to ensure code quality and consistency.

TypeScript Guidelines

• Use TypeScript for all new code
• Follow the official TypeScript style guide
• Use strict mode and explicit types
• Prefer interfaces over types for public APIs
• Use nullable types (type | null) rather than undefined parameters

// Good
interface UserProfile {
  id: string;
  name: string;
  email: string | null;
  preferences: UserPreferences;
}
 
// Avoid
type UserProfile = {
  id: string;
  name: string;
  email?: string;
  preferences?: {
    theme?: string;
    notifications?: boolean;
  }
}

Code Style

ThinkCode uses ESLint and Prettier to enforce code style:

• 2 spaces for indentation
• Single quotes for strings
• Semicolons at the end of statements
• No trailing commas in function calls
• Trailing commas in object and array literals
• Maximum line length of 100 characters

Our ESLint configuration enforces these rules. You can check your code using:

# Check code style
pnpm lint
 
# Fix automatically fixable issues
pnpm lint:fix

Component Architecture

When developing UI components:

• Follow a functional approach
• Use React hooks instead of class components
• Keep components small and focused
• Document component props with JSDoc comments
• Include accessibility attributes

/**
 * A button component with AI-assisted actions
 * @param text - The button text
 * @param action - The AI action to perform
 * @param variant - Visual style variant
 */
export function AIButton({
  text,
  action,
  variant = 'primary',
  disabled = false
}: AIButtonProps) {
  const handleClick = useCallback(() => {
    // Implementation
  }, [action]);
  
  return (
    <button 
      className={`ai-button ai-button--${variant}`}
      onClick={handleClick}
      disabled={disabled}
      aria-label={text}
    >
      {text}
    </button>
  );
}

Testing Guidelines

All code should be tested:

• Unit tests: For individual functions and components
• Integration tests: For interactions between components
• End-to-end tests: For complete features
• Visual regression tests: For UI components

We use the following testing tools:

• Jest for unit and integration tests
• Playwright for end-to-end tests
• Storybook for component testing

Tests should be placed in a __tests__ directory adjacent to the code being tested:

src/
├── components/
│   ├── Button.tsx
│   ├── __tests__/
│   │   └── Button.test.tsx

The Contribution Process

Finding Issues to Work On

• Check the Good First Issues label
• Look at the Help Wanted issues
• Read the Roadmap for future plans

Making Changes

1. Create a new branch for your feature or bugfix:

git checkout -b feature/my-feature
# or
git checkout -b fix/my-bugfix

2. Make your changes and commit them following our commit message guidelines
3. Keep your branch updated with upstream:

git fetch upstream
git rebase upstream/main

4. Ensure your changes pass all tests:

pnpm test

Commit Message Guidelines

We follow conventional commits for our commit messages:

• feat: - A new feature
• fix: - A bug fix
• docs: - Documentation changes
• style: - Changes that don't affect the code's meaning (formatting, etc.)
• refactor: - Code changes that neither fix a bug nor add a feature
• perf: - Changes that improve performance
• test: - Adding or correcting tests
• chore: - Changes to the build process or auxiliary tools

Examples:

feat: add AI code completion for Python
fix: resolve permission issue in file access API
docs: update API reference for context providers

Pull Request Process

1. Push your branch to your fork:

git push origin feature/my-feature

2. Open a pull request against the main ThinkCode repository
3. Fill out the pull request template with all required information
4. Wait for the CI checks to complete
5. Address any review comments

Code Review Process

All contributions go through a code review process:

1. A maintainer will review your code for:
   • Functionality
   • Code quality
   • Test coverage
   • Documentation
2. CI checks verify that your changes:
   • Build successfully
   • Pass all tests
   • Meet code style requirements
   • Don't introduce performance regressions
3. You may need to make changes based on review feedback
4. Once approved, a maintainer will merge your pull request

Documentation

Documentation is crucial for any contribution:

Code Documentation

• Use JSDoc comments for functions, classes, and interfaces
• Document parameters, return values, and thrown exceptions
• Provide examples for complex APIs

/**
 * Registers a custom context provider with ThinkCode.
 * 
 * @param provider - The context provider implementation
 * @returns A disposable that can be used to unregister the provider
 * @example
 * ```typescript
 * const provider = {
 *   id: 'my-provider',
 *   // ... provider implementation
 * };
 * 
 * const disposable = registerContextProvider(provider);
 * 
 * // Later, to unregister:
 * disposable.dispose();
 * ```
 */
export function registerContextProvider(
  provider: ContextProvider
): Disposable {
  // Implementation
}

Feature Documentation

For new features, update or create:

1. User documentation in the /docs directory
2. API reference documentation
3. Examples in the /examples directory
4. Developer notes in code comments

Releasing and Versioning

ThinkCode follows Semantic Versioning (SemVer):

• Major version (1.0.0): Incompatible API changes
• Minor version (0.1.0): New features in a backward-compatible manner
• Patch version (0.0.1): Backward-compatible bug fixes

Release process:

1. Version bump and changelog updates are automated based on conventional commits
2. Release candidates are created for testing before final releases
3. Stable releases are created from the main branch
4. Hot fixes may be applied to release branches

Community Guidelines

Communication Channels

• GitHub Issues: For bug reports and feature requests
• Discussions: For questions and general discussion
• Discord: For real-time communication
• Weekly Meetings: For contributors and maintainers

Code of Conduct

All contributors must follow our Code of Conduct, which ensures a welcoming and inclusive environment for everyone.

Recognition

Contributors are recognized in several ways:

• Attribution in the changelog
• Listing in the Contributors section
• Recognition in release notes
• Community spotlights for significant contributions

Working with AI Features

ThinkCode integrates various AI technologies. When contributing to AI features:

AI Model Integration

• Understand the models being used
• Test with both online and offline models
• Document API parameters and expected outputs
• Consider model version compatibility

Context Management

When modifying context providers:

• Respect privacy considerations
• Maintain backward compatibility
• Document the context format
• Test with various context sizes

AI Ethics Guidelines

• Ensure AI features respect user privacy
• Avoid bias in AI-generated content
• Provide user control over AI functionality
• Document limitations and potential issues

Troubleshooting

If you encounter issues during development:

Common Development Issues

1. Dependency errors: Run pnpm install --force to resolve dependency conflicts
2. Build failures: Check the error log and ensure you have the correct Node.js version
3. Test failures: Run tests with --verbose flag for detailed output
4. TypeScript errors: Use VSCode to identify issues or run pnpm type-check

Getting Help

• Ask in the Discord developer channel
• Create a "Help Wanted" issue
• Check the developer documentation
• Attend office hours for contributor support

Additional Resources

• ThinkCode Architecture Reference
• API Documentation
• Extension Development Guide
• ThinkCode Design System
• Performance Profiling Guide

Thank you for contributing to ThinkCode! Your efforts help build a better tool for developers worldwide.