cline/CONTRIBUTING.md

Contributing to Cline

We're thrilled you're interested in contributing to Cline. Whether you're fixing a bug, adding a feature, or improving our docs, every contribution makes Cline smarter! To keep our community vibrant and welcoming, all members must adhere to our Code of Conduct.

Reporting Bugs or Issues

Bug reports help make Cline better for everyone! Before creating a new issue, please search existing ones to avoid duplicates. When you're ready to report a bug, head over to our issues page where you'll find a template to help you with filling out the relevant information.

🔐 Important: If you discover a security vulnerability, please use the Github security tool to report it privately.

Before Contributing

All contributions must begin with a GitHub Issue, unless the change is for small bug fixes, typo corrections, minor wording improvements, or simple type fixes that don't change functionality. For features and contributions:

• First check the Feature Requests discussions board for similar ideas
• If your idea is new, create a new feature request
• Wait for approval from core maintainers before starting implementation
• Once approved, feel free to begin working on a PR with the help of our community!

PRs without approved issues may be closed.

Deciding What to Work On

Looking for a good first contribution? Check out issues labeled "good first issue" or "help wanted". These are specifically curated for new contributors and areas where we'd love some help!

We also welcome contributions to our documentation! Whether it's fixing typos, improving existing guides, or creating new educational content - we'd love to build a community-driven repository of resources that helps everyone get the most out of Cline. You can start by diving into /docs and looking for areas that need improvement.

Development Setup

Local Development Instructions

1. Clone the repository (Requires git-lfs):

   git clone https://github.com/cline/cline.git
   

2. Open the project in VSCode:

   code cline
   

3. Install bun
4. Install the necessary dependencies for the extension and webview-gui:

   cd apps/vscode && bun run install:all && cd ../..
   cd sdk && bun run build && cd ..
   

5. Generate Protocol Buffer files (required before first build):
6. Launch by pressing F5 (or Run->Start Debugging) to open a new VSCode window with the extension loaded. (You may need to install the esbuild problem matchers extension if you run into issues building the project.)

Creating a Pull Request

1. Commit your changes.

2. Push your branch and create a PR on GitHub. Our CI will:

   • Run tests and checks

3. Testing

   • Run cd apps/vscode && bun run test to run tests locally.
   • Before submitting PR, run bun run format:fix to format your code

Extension

1. VS Code Extensions

   • When opening the project, VS Code will prompt you to install recommended extensions
   • These extensions are required for development - please accept all installation prompts
   • If you dismissed the prompts, you can install them manually from the Extensions panel

2. Local Development

   • cd into the vscode extension, cd apps/vscode
   • Run bun run install:all to install dependencies
   • Run bun run protos to generate Protocol Buffer files (required before first build)
   • Run bun run test to run tests locally
   • Run → Start Debugging or >Debug: Select and Start Debugging and wait for a new VS Code instance to open
   • Terminal Workflow: Use bun run dev (generates protos + runs watch mode) or bun run watch (if protos already generated)
   • Before submitting PR, run bun run format:fix to format your code

3. Linux-specific Setup VS Code extension tests on Linux require the following system libraries:

   • dbus
   • libasound2
   • libatk-bridge2.0-0
   • libatk1.0-0
   • libdrm2
   • libgbm1
   • libgtk-3-0
   • libnss3
   • libx11-xcb1
   • libxcomposite1
   • libxdamage1
   • libxfixes3
   • libxkbfile1
   • libxrandr2
   • xvfb

   These libraries provide necessary GUI components and system services for the test environment.

   For example, on Debian-based distributions (e.g., Ubuntu), you can install these libraries using apt:

   sudo apt update
   sudo apt install -y \
     dbus \
     libasound2 \
     libatk-bridge2.0-0 \
     libatk1.0-0 \
     libdrm2 \
     libgbm1 \
     libgtk-3-0 \
     libnss3 \
     libx11-xcb1 \
     libxcomposite1 \
     libxdamage1 \
     libxfixes3 \
     libxkbfile1 \
     libxrandr2 \
     xvfb
   

Writing and Submitting Code

Anyone can contribute code to Cline, but we ask that you follow these guidelines to ensure your contributions can be smoothly integrated:

1. Keep Pull Requests Focused

   • Limit PRs to a single feature or bug fix
   • Split larger changes into smaller, related PRs
   • Break changes into logical commits that can be reviewed independently

2. Code Quality

   • Run bun run lint to check code style
   • Run bun run format to automatically format code
   • All PRs must pass CI checks which include both linting and formatting
   • Address any warnings or errors from linter before submitting
   • Follow TypeScript best practices and maintain type safety

3. Testing

   • Add tests for new features
   • Run bun test to ensure all tests pass
   • Update existing tests if your changes affect them
   • Include both unit tests and integration tests where appropriate

   End-to-End (E2E) Testing

   Cline includes comprehensive E2E tests using Playwright that simulate real user interactions with the extension in VS Code:

   • Running E2E tests:

     bun run test:e2e        # Build and run all E2E tests
     bun run e2e             # Run tests without rebuilding
     bun run test:e2e -- --debug  # Run with interactive debugger
     

   • Writing E2E tests:

     • Tests are located in src/test/e2e/
     • Use the e2e fixture for single-root workspace tests
     • Use e2eMultiRoot fixture for multi-root workspace tests
     • Follow existing patterns in auth.test.ts, chat.test.ts, diff.test.ts, and editor.test.ts
     • See src/test/e2e/README.md for detailed documentation

   • Debug mode features:

     • Interactive Playwright Inspector for step-by-step debugging
     • Record new interactions and generate test code automatically
     • Visual VS Code instance for manual testing
     • Element inspection and selector validation

   • Test environment:

     • Automated VS Code setup with Cline extension loaded
     • Mock API server for backend testing
     • Temporary workspaces with test fixtures
     • Video recording for failed tests

4. Versioning & Changelog Notes

   • Contributors do not need to create changelog-entry files as part of PRs.
   • Maintainers handle release versioning and changelog curation during the release process.

5. Commit Guidelines

   • Write clear, descriptive commit messages
   • Use conventional commit format (e.g., "feat:", "fix:", "docs:")
   • Reference relevant issues in commits using #issue-number

6. Before Submitting

   • Rebase your branch on the latest main
   • Ensure your branch builds successfully
   • Double-check all tests are passing
   • Review your changes for any debugging code or console logs

7. Pull Request Description

   • Clearly describe what your changes do
   • Include steps to test the changes
   • List any breaking changes
   • Add screenshots for UI changes

Contribution Agreement

By submitting a pull request, you agree that your contributions will be licensed under the same license as the project (Apache 2.0).

Remember: Contributing to Cline isn't just about writing code - it's about being part of a community that's shaping the future of AI-assisted development. Let's build something amazing together! 🚀