Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
159 lines (116 loc) · 7.56 KB

CONTRIBUTING.md

File metadata and controls

159 lines (116 loc) · 7.56 KB

Contributing to GitHub Copilot for Eclipse

Thank you for your interest in contributing to GitHub Copilot for Eclipse! This document provides guidelines and instructions for contributing to this project.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any questions or concerns.

Contributor License Agreement (CLA)

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

Getting Started

Prerequisites

  • Java 17 or later (CI uses Temurin 17; use a newer JDK if required by your Eclipse IDE)
  • Maven 3.8+ (or use the provided Maven wrapper ./mvnw)
  • Node.js 22.13 or later, with npm
  • Eclipse IDE for Eclipse Committers 2024-03 or later (for development)
  • Recommended: Eclipse Checkstyle plugin for code style compliance (e.g. install from update site: https://checkstyle.org/eclipse-cs-update-site/)

Building the Project

Clone the repository, install the Copilot agent dependencies, and build with the Maven wrapper:

cd com.microsoft.copilot.eclipse.core/copilot-agent
npm i -f
cd ../..
./mvnw clean package

The npm i -f step runs the Copilot agent postinstall script, which copies the language server files into com.microsoft.copilot.eclipse.core/copilot-agent/dist/ and the platform-specific agent bundles required by the Tycho build. The -f flag matches CI and lets npm proceed if the agent dependency tree has conflicts.

Running Tests

./mvnw test

Building the Update Site

./mvnw clean verify

The installable P2 repository is generated in com.microsoft.copilot.eclipse.repository/target/repository/.

Running in Eclipse

  1. Import all modules into your Eclipse workspace.
    • Select File > Import... > General > Existing projects into Workspace, select the root directory of the copilot-for-eclipse git repo, activate the check box Search for nested projects, and finish the wizard.
    • Do also import the agent bundle for your OS (e.g., com.microsoft.copilot.eclipse.core.agent.win32) after building the project with npm and maven or import all OS-specific agent bundles.
  2. Activate one of the target platforms, i.e. open one of the target definition files and select Set As Active Target Platform.
    • target-terminal.target (Eclipse 4.37+)
    • target-tm-terminal.target (Eclipse 4.36 and earlier)
  3. For using the Checkstyle configuration (assuming you have installed the Eclipse Checkstyle plugin, see prerequisites), add a new named Checkstyle configuration.
    • Select Window > Preferences > Checkstyle and press the New... button.
    • Select Type="Project Relative Configuration", name="copilot4eclipse", and choose the location using the Browse... button. The checkstyle.xml file is in the git repository root folder in the project "github-copilot-for-eclipse".
  4. Use the launch configurations in the launch/ directory, e.g. for launching a new Eclipse IDE with Copilot plug-ins.
    • Check the selected plug-ins in your launch configuration (in Plug-ins tab) and remove any OS-specific agent bundle that does not fit to your OS and remove all test bundles from the selected plug-ins from your Eclipse workspace.
    • Validate your config and ensure that all dependencies are resolved. Try Select Required button if something is missing.

How to Contribute

Reporting Issues

  • Search existing issues before filing a new one to avoid duplicates.
  • File bugs or feature requests as a new GitHub Issue.
  • Include steps to reproduce, expected behavior, actual behavior, and your environment details (Eclipse version, OS, Java version).

Submitting Pull Requests

  1. Fork the repository and create a feature branch from main.
  2. Make your changes following the code style and architecture guidelines below.
  3. Ensure all checks pass before submitting: 
    cd com.microsoft.copilot.eclipse.core/copilot-agent
npm i -f
cd ../..
./mvnw checkstyle:check   # Code style compliance
./mvnw clean verify       # Compilation and packaging
./mvnw test               # Unit tests
  4. Open a pull request with a clear description of the change and its motivation.
  5. Address any feedback from reviewers.

Security Vulnerabilities

Please do not report security vulnerabilities through public GitHub issues. For security reporting information, please review the guidance at https://aka.ms/SECURITY.md.

Project Structure

The project is a multi-module Maven/Tycho build consisting of OSGi bundles:

Module Purpose
com.microsoft.copilot.eclipse.core Core functionality: LSP client, authentication, chat/completion logic
com.microsoft.copilot.eclipse.ui User interface: chat view, completion UI, agent tools
com.microsoft.copilot.eclipse.ui.jobs Copilot Jobs view integration
com.microsoft.copilot.eclipse.terminal.api Terminal tool API definitions
com.microsoft.copilot.eclipse.ui.terminal Terminal integration (Eclipse 4.37+)
com.microsoft.copilot.eclipse.ui.terminal.tm TM Terminal integration (Eclipse 4.36 and earlier)
com.microsoft.copilot.eclipse.branding Product branding and about dialog
com.microsoft.copilot.eclipse.core.agent.* Platform-specific Copilot language server agent bundles
com.microsoft.copilot.eclipse.feature Eclipse feature definition
com.microsoft.copilot.eclipse.repository P2 update site
com.microsoft.copilot.eclipse.core.test Core bundle tests
com.microsoft.copilot.eclipse.ui.test UI bundle tests

Code Style

This project enforces Google Java Style (with customizations) via Checkstyle. The configuration is in checkstyle.xml.

Development Guidelines

Threading

  • Never block the UI thread with I/O or long-running operations.
  • Use CompletableFuture.runAsync() or Eclipse Job API for background work.
  • Always update SWT widgets on the UI thread using Display.asyncExec() or Display.syncExec().

Resource Management

  • Dispose SWT resources (fonts, images) when done.
  • Use try-with-resources for streams and Eclipse resources.
  • Close editors before deleting files.

Error Handling

  • Use Eclipse IStatus / Status objects for error reporting.
  • Log errors via CopilotCore.getPlugin().logError(message, exception).
  • Never silently swallow exceptions.

Dependencies

  • Minimize bundle dependencies — only add what is necessary.
  • Avoid circular dependencies between bundles.
  • Use Require-Bundle for essential dependencies, Import-Package for optional or version-flexible ones.

Testing

  • Use JUnit 5 (Jupiter) for new tests.
  • Name test classes <ClassName>Test or <ClassName>Tests.
  • Name test methods descriptively: testMethodName_scenario_expectedOutcome.
  • Clean up resources in teardown methods.