Thank you for your interest in contributing to PocketLLM! This document provides guidelines and best practices for contributing to the project.

• Getting Started
• Development Setup
• Code Style
• Making Changes
• Testing
• Documentation
• Pull Request Process
• Community Guidelines

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

   git clone https://github.com/your-username/pocketllm.git

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

   git checkout -b feature/your-feature-name

1. Install Flutter SDK (version 3.0 or later)
2. Install dependencies:

   cd pocketllm
   flutter pub get

3. Verify setup:

   flutter doctor

1. Install Node.js (version 18 or later)
2. Install dependencies:

   cd pocketllm-backend
   npm install

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration

• Follow the Effective Dart style guide
• Use flutter format to format code:

  flutter format .

• Keep functions small and focused
• Use meaningful variable and function names
• Add comments for complex logic

• Follow the Google TypeScript Style Guide
• Use Prettier for formatting:

  npm run format

• Use ESLint for linting:

  npm run lint

1. Make your changes in your feature branch
2. Follow the existing code style and patterns
3. Add or update tests as necessary
4. Update documentation if needed
5. Run all tests to ensure nothing is broken

• Use clear, descriptive commit messages
• Follow the Conventional Commits specification
• Example formats:
  • feat: add new model provider integration
  • fix: resolve chat history loading issue
  • docs: update API documentation
  • test: add unit tests for chat service

# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

# Run specific test file
flutter test test/services/chat_service_test.dart

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:cov

• Write unit tests for business logic
• Write widget tests for UI components
• Write integration tests for critical user flows
• Aim for high test coverage (80%+)

• Document all public APIs with clear comments
• Use Dart doc comments for Flutter code:

  /// A service that manages chat functionality.
  ///
  /// This service handles creating, updating, and deleting chats,
  /// as well as sending and receiving messages.
  class ChatService {
    // ...
  }

• Use JSDoc comments for TypeScript code:

  /**
   * Creates a new chat session for a user.
   * @param userId - The ID of the user creating the chat
   * @param title - The title of the new chat
   * @returns The created chat object
   */

• Update README.md for major features
• Add new documentation files to the docs/ directory
• Keep the AGENTS.md file updated for AI agent guidance

1. Ensure all tests pass
2. Update documentation as needed
3. Squash related commits for clarity
4. Submit pull request with clear description:
   • What changed and why
   • How to test the changes
   • Any breaking changes
5. Respond to feedback promptly
6. Wait for review and approval

## Description

Brief description of the changes and why they were made.

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement

## Testing

- [ ] Tests pass locally
- [ ] Added new tests
- [ ] Updated existing tests

## Checklist

- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No new warnings

• Be respectful and inclusive
• Provide constructive feedback
• Help others learn and grow
• Focus on the code, not the person

• Use clear, professional language
• Explain technical concepts accessibly
• Be patient with newcomers
• Keep discussions focused and productive

If you need help:

1. Check existing issues and documentation
2. Join our community discussions
3. Ask questions in a clear, detailed manner
4. Provide relevant code snippets or error messages

Your contributions make PocketLLM better for everyone. Thank you for taking the time to contribute!