Skip to content

Latest commit

 

History

History
135 lines (90 loc) · 7.74 KB

CONTRIBUTING.md

File metadata and controls

135 lines (90 loc) · 7.74 KB
Raw

Contributing to Eclipse LSP4E

Welcome to the Eclipse LSP4E contributor land, and thanks in advance for your help in making Eclipse LSP4E better and better!

🏠 Official Eclipse LSP4E Git repo is https://github.com/eclipse-lsp4e/lsp4e . (All other repositories, mirrors and so on are legacy repositories that should be removed at some point, so please don't use them!)

⚖️ Legal and Eclipse Foundation terms

The project license is available at LICENSE.

This Eclipse Foundation open project is governed by the Eclipse Foundation Development Process and operates under the terms of the Eclipse IP Policy.

Before your contribution can be accepted by the project team, contributors must have an Eclipse Foundation account and must electronically sign the Eclipse Contributor Agreement (ECA).

For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit.

💬 Get in touch with the community

Eclipse LSP4E use mainly 2 channels for strategical and technical discussions

🆕 Trying latest builds

Latest snapshot builds, for testing, can usually be found at https://download.eclipse.org/lsp4e/snapshots/ .

🧑‍💻 Developer resources

⌨️ Setting up the Development Environment

Install Software

  1. Install the Eclipse IDE for Eclipse Committers from https://www.eclipse.org/downloads/packages/ or any another Eclipse distribution with:
    1. Plug-in Development Environment (PDE) installed
    2. Eclipse m2e installed
  2. To run Maven builds from the command line, install JDK17 and Maven 3.9.x

Import Project

  1. Clone this repository Clone to Eclipse IDE for LSP4E.
  2. File > Open Projects from Filesystem... , select the path to the LSP4E Git repo and the relevant children projects you want to import
  3. Depending on the task you're planning to work on, multiple workflows are available to configure the target-platform
    • In many cases, this simplest workflow will be sufficient: Install latest LSP4E snapshot in your target-platform (can be your current IDE), or
    • If you don't want to mix versions of LSP4E, open target-platforms/target-platform-latest/target-platform-latest.target from within Eclipse and click Set as Active Target-Platform in the top right corner.
  4. Open the project modules you want to work on (right-click > Open project) and their dependencies
  5. Happy coding! 🤗

🏗️ Build

  • From the command line run:
    • on Windows mvnw clean verify
    • on Linux/MacOS ./mvnw clean verify
  • From within Eclipse: right-click on the LSP4E root folder > Run As > Maven build

Running single unit tests via the command line

To run single unit tests via the command line, one can use the following command from the project's root:

./mvnw -Dtest=<TestClassName>#<MethodName> -DfailIfNoTests=false verify

For example:

./mvnw -Dtest=HighlightTest#testCheckIfOtherAnnotationsRemains -DfailIfNoTests=false verify

To run a unit test in JVM debug mode via the command line one can use:

./mvnw -Dtest=<TestClassName>#<MethodName> -DfailIfNoTests=false -Dtycho.testArgLine="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=localhost:8000" verify

Once Maven is about to execute the test it will wait for you to attach to the test JVM using a remote debugger, e.g. using Eclipse's Remote Java Application debug configuration.

Running the CI job locally:

The GitHub actions wokflow is compatible with nektos/act a command-line tool that allows you to run GitHub action workflows locally.

  1. Install the docker engine
  2. Install nektos/act
  3. From the command line navigate into the LSP4E project root
  4. Run the command act
  5. On subsequent re-runs you can use act -r to reuse previous container which avoids reinstallation system packages and reduces build time.

In case of build failures the docker container will still be running and you can ssh into it for analysis using docker exec -u root -it <CONTAINER_ID> /bin/bash, e.g.:

container_id=$(docker container ps --filter status=running --filter name=act-Build-build --format {{.ID}})
docker exec -u root -it $container_id /bin/bash

⬆️ Version bump

LSP4E tries to use OSGi Semantic Version (to properly expose its API contracts and breakage) and Reproducible Version Qualifiers (to minimize the avoid producing multiple equivalent artifacts for identical source). This requires the developer to manually bump version from time to time. Some rules are that:

  • Versions are bumped on a per module grain (bump version of individual bundles/features one by one when necessary), DON'T bump version of parent pom, nor of other modules you don't change
  • Versions are bumped maximum once per release (don't bump versions that were already bumped since last release)
  • Don't bump versions of what you don't change
  • Bump version of the bundles you're modifying only if it's their 1st change since last release
  • Version bump may need to be cascaded to features that include the artifact you just changed, and then to features that include such features and so on (unless the version of those features were already bumped since last release).

The delta for version bumps are:

  • +0.0.1 (next micro) for a bugfix, or an internal change that doesn't surface to APIs
  • +0.1.0 (next minor) for an API addition
  • +1.0.0 (next major) for an API breakage (needs to be discussed on the mailing-list first)
  • If some "smaller" bump already took place, you can replace it with your "bigger one". Eg, if last release has org.eclipse.lsp4e 1.16.1; and someone already bumped version to 1.16.2 (for an internal change) and you're adding a new API, then you need to change version to 1.17.0

➕ Submit changes

LSP4E only accepts contributions via GitHub Pull Requests against https://github.com/eclipse-lsp4e/lsp4e repository.

Before sending us a pull request, please ensure that:

  1. You are working against the latest source on the main branch.
  2. You check existing open and recently merged pull requests to make sure someone else hasn't already addressed the issue.

To send us a pull request, please:

  1. Fork the repository.
  2. Modify the source while focusing on the specific change you are contributing.
  3. Commit to your fork using clear, descriptive commit messages.
  4. Send us a pull request, answering any default questions in the pull request interface.

GitHub provides additional documentation on forking a repository and creating a pull request