diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3dee8ab..f0cf9fad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,24 +1,153 @@ -Working on the plugin -===================== +# Contributing to Cucumber Eclipse -You should be able to work on the plugin by cloning this repository: +Thank you for your interest in contributing to Cucumber Eclipse! This document provides guidelines and instructions for setting up your development environment and contributing to the project. - git clone git@github.com:cucumber/cucumber-eclipse.git +## Setting Up Your Development Environment -You can then import the 4 plugin projects into Eclipse. +### Quick Setup with Oomph (Recommended) -We have arbitrarily decided to support Eclipse 3.5+ - hopefully this will cover most development kits that don't stick to the bleeding edge of Eclipse versions, however if there is an overriding reason to use a more recent version of the eclipse APIs, this is not set in stone. When adding dependencies to the plugins, make sure to add them as version [3.5,0). +The easiest way to get started is using the Oomph setup file: -Modules list -============ +1. Download and run the [Eclipse Installer](https://www.eclipse.org/downloads/packages/installer) +2. Switch to "Advanced Mode" (menu icon in top-right) +3. Add the project setup file: `https://raw.githubusercontent.com/laeubi/cucumber-eclipse/main/CucumberEclipse.setup` +4. Follow the wizard to complete the setup -Plugins: +For detailed instructions, see the [README.md](README.md#setting-up-development-environment). -* cucumber.eclipse.editor - an editor for .feature files - will use step definitions from integration implementions if they exist -* cucumber.eclipse.runner - runs a feature file wrapped up in a JUnit test. Initially will depend on the steps integration implementation. -* cucumber.eclipse.steps.integration - an extension point for plugins that supply a means to deduce a list of all steps defined in a project -* cucumber.eclipse.steps.jdt - an implementation of the integration extension point that uses Eclipse JDT to find steps. +### Manual Setup -Feature: +If you prefer manual setup: -* cucumber.eclipse.feature - an Eclipse feature set that includes all of the above plugins. +1. **Clone the repository:** + ```bash + git clone git@github.com:cucumber/cucumber-eclipse.git + cd cucumber-eclipse + ``` + +2. **Import all projects into Eclipse:** + - Use `File` → `Import` → `Existing Projects into Workspace` + - Select the repository root and enable "Search for nested projects" + - Import all projects + +3. **Set the target platform:** + - Open `io.cucumber.eclipse.targetdefinition/cucumber.eclipse.targetdefinition.target` + - Click "Set as Active Target Platform" + +4. **Build the workspace:** + - `Project` → `Clean...` → Clean all projects + +## Project Structure + +### Plugins + +* **io.cucumber.eclipse.editor** - Core editor functionality for `.feature` files, syntax highlighting, and content assist +* **io.cucumber.eclipse.java** - Java/JVM backend integration with step definition detection and navigation +* **io.cucumber.eclipse.java.plugins** - Plugin extensions for Java backend (additional integrations) +* **io.cucumber.eclipse.python** - Python/Behave backend integration +* **io.cucumber.eclipse.feature** - Eclipse feature definition that packages all plugins +* **io.cucumber.eclipse.product** - Product configuration for standalone distribution +* **io.cucumber.eclipse.updatesite** - P2 update site for plugin distribution + +### Supporting Modules + +* **io.cucumber.eclipse.targetdefinition** - Target platform definition (Eclipse platform and dependencies) +* **examples/** - Example projects demonstrating plugin usage + +## Building the Project + +### Using Maven (Command Line) + +Build all modules: +```bash +mvn clean install +``` + +The update site will be built in `io.cucumber.eclipse.updatesite/target/repository/`. + +### Using Eclipse (IDE) + +Eclipse will automatically build the projects when you make changes. To trigger a manual build: +- `Project` → `Clean...` → Clean all projects + +## Running and Testing + +### Running the Plugin in Development + +1. Right-click on any plugin project +2. Select `Run As` → `Eclipse Application` +3. A new Eclipse instance will launch with your plugin installed + +### Creating a Launch Configuration + +1. Go to `Run` → `Run Configurations...` +2. Create a new "Eclipse Application" configuration +3. Set appropriate VM arguments if needed (e.g., `-Xmx2048m`) +4. Run the configuration + +### Running Tests + +Tests are run automatically during the Maven build. To run them manually: + +```bash +mvn clean verify +``` + +## Making Changes + +### Code Style + +- Follow Eclipse Java code conventions +- Use meaningful variable and method names +- Add comments for complex logic +- Keep changes focused and minimal + +### Commit Guidelines + +- Write clear, descriptive commit messages +- Reference issue numbers in commits (e.g., "Fix #123: Description") +- Keep commits atomic (one logical change per commit) +- Sign-off your commits if required by the project + +### Pull Request Process + +1. Fork the repository +2. Create a feature branch from `main` +3. Make your changes with appropriate tests +4. Ensure all tests pass +5. Push to your fork and submit a pull request +6. Wait for review and address any feedback + +## Requirements and Dependencies + +- **Java**: Java 21 or higher (JDK 21) +- **Eclipse**: Eclipse 2024-06 or later (IDE for Eclipse Committers recommended) +- **Maven**: Maven 3.6+ (for command-line builds) +- **Target Platform**: Eclipse 2025-09 (or compatible release) + +## Adding Dependencies + +When adding dependencies to plugins: + +1. Add to the appropriate `MANIFEST.MF` file +2. Ensure compatibility with the target platform +3. Update the target definition if adding external dependencies +4. Document the dependency requirement + +## Resources + +- [Eclipse Plugin Development](https://www.eclipse.org/pde/) +- [Tycho Maven Plugin](https://www.eclipse.org/tycho/) +- [Cucumber Documentation](https://cucumber.io/docs) +- [Project Wiki](https://github.com/cucumber/cucumber-eclipse/wiki) + +## Getting Help + +- Check existing issues on GitHub +- Review the project wiki +- Ask questions in pull requests or issues +- Join community discussions + +## License + +By contributing to Cucumber Eclipse, you agree that your contributions will be licensed under the project's license. diff --git a/CucumberEclipse.setup b/CucumberEclipse.setup new file mode 100644 index 00000000..2c8727c2 --- /dev/null +++ b/CucumberEclipse.setup @@ -0,0 +1,112 @@ + + + + + https://raw.githubusercontent.com/cucumber/cucumber-eclipse/main/io.cucumber.eclipse.editor/icons/cukes.gif + + + https://github.com/cucumber/cucumber-eclipse + + + + Define the JRE needed to compile and run the Java projects of ${scope.project.label} + + + Set the heap space needed to work with the projects of ${scope.project.label} + + + + + + Install the tools needed in the IDE to work with the source code for ${scope.project.label} + + + + + github.remoteURIs + + + ${scope.project.label} Github repository + + + remoteURI + + + ${scope.project.label} + + + + + + ${git.clone.cucumber.eclipse.location}/io.cucumber.eclipse.targetdefinition/cucumber.eclipse.targetdefinition.target + + + + + Import all projects from the repository + + + + + + + + The dynamic working set for ${scope.project.label} + + + The main development branch + + + Cucumber Eclipse provides IDE support for Cucumber in Eclipse + diff --git a/README.md b/README.md index 3456ac8d..ee3b4879 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,94 @@ To manage these features: 2. Find the "Cucumber" category 3. Check or uncheck the activities you want to enable or disable +## Setting Up Development Environment + +### Prerequisites + +- **Eclipse IDE**: Eclipse IDE for Eclipse Committers (2024-06 or later) - [Download](https://www.eclipse.org/downloads/packages/) +- **Java 21**: JDK 21 or higher - [Download](https://adoptium.net/) +- **Maven**: Maven 3.6+ (for command-line builds) - [Download](https://maven.apache.org/) + +### Option 1: Using Oomph (Recommended) + +[Oomph](https://wiki.eclipse.org/Eclipse_Oomph_Installer) is Eclipse's installation and project provisioning system that automates the setup process. + +1. **Download and launch Eclipse Installer** + - Download from [Eclipse Installer](https://www.eclipse.org/downloads/packages/installer) + - Start the Eclipse Installer + +2. **Switch to Advanced Mode** + - Click the menu icon (☰) in the top-right corner + - Select "Advanced Mode" + +3. **Add the Cucumber Eclipse Setup** + - Click the "+" icon to add a new project + - Select "Github Projects" as the catalog + - Paste the setup file URL: + ``` + https://raw.githubusercontent.com/cucumber/cucumber-eclipse/main/CucumberEclipse.setup + ``` + - Or use a local file if you've already cloned the repository: + ``` + file:/path/to/cucumber-eclipse/CucumberEclipse.setup + ``` + +4. **Select Product and Project** + - Select "Eclipse IDE for Eclipse Committers" as the product + - Check "Cucumber Eclipse" in the project list + - Click "Next" + +5. **Configure Variables** + - Set your desired installation and workspace locations + - Configure GitHub credentials (if you want to contribute) + - Click "Next" and then "Finish" + +6. **Wait for Setup** + - Oomph will now: + - Install required Eclipse features (PDE, M2E) + - Clone the Cucumber Eclipse repository + - Set up the target platform + - Import all plugin projects + - Configure workspace preferences + - This may take several minutes depending on your internet connection + +7. **Start Development** + - Once setup completes, Eclipse will open with all projects imported + - The target platform will be automatically set + - You're ready to start developing! + +### Option 2: Manual Setup + +If you prefer to set up the environment manually: + +1. **Clone the repository** + ```bash + git clone https://github.com/cucumber/cucumber-eclipse.git + cd cucumber-eclipse + ``` + +2. **Import projects into Eclipse** + - Open Eclipse IDE for Eclipse Committers + - Go to `File` → `Import` → `General` → `Existing Projects into Workspace` + - Select the cloned repository root directory + - Make sure "Search for nested projects" is checked + - Select all projects and click "Finish" + +3. **Set the target platform** + - Open `io.cucumber.eclipse.targetdefinition/cucumber.eclipse.targetdefinition.target` + - Wait for the target platform to resolve (this may take a few minutes) + - Click "Set as Active Target Platform" in the top-right corner of the editor + +4. **Configure Java 21** + - Go to `Window` → `Preferences` → `Java` → `Installed JREs` + - Add JDK 21 if not already present + - Ensure it's set as the default + +5. **Build the workspace** + - Go to `Project` → `Clean...` + - Select "Clean all projects" and click "OK" + - Wait for the automatic build to complete + ## Build and install from source To use the latest features, you can choose to build and install from source.