diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b272d07866..0fb23e8b8a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,37 @@ Thanks for your interest in this project. +## Table of Contents +1. [Try SNAPSHOTs and report issues](#try-snapshots-and-report-issues) +2. [Development Environment](#development-environment) + 1. [Prerequisites](#prerequisites) + 2. [Using the Eclipse Installer (Oomph)](#using-the-eclipse-installer-oomph) + 3. [Manual Setup](#manual-setup) +3. [Tests](#tests) + 1. [Tycho Integration Tests](#tycho-integration-tests) + 2. [Writing Tycho Integration Tests](#writing-tycho-integration-tests) + 1. [Tips on the naming of integration tests](#tips-on-the-naming-of-integration-tests) +4. [🏗️ Build & Test](#🏗️-build--test) +5. [Debugging](#debugging) +6. [Commits](#commits) + 1. [Message Guidelines](#message-guidelines) + 2. [Granularity](#granularity) +7. [Submit Patch](#submit-patch) +8. [Increasing Versions](#increasing-versions) +9. [Backporting](#backporting) +10. [Advanced development tricks](#advanced-development-tricks) + 1. [Building Tycho against a locally built version of p2](#building-tycho-against-a-locally-built-version-of-p2) + 2. [Running with a locally built version of the JDT compiler](#running-with-a-locally-built-version-of-the-jdt-compiler) + 3. [Updating the Equinox and JDT dependencies of Tycho](#updating-the-equinox-and-jdt-dependencies-of-tycho) + 4. [Profiling the Tycho build](#profiling-the-tycho-build) + 1. [Add timestamps to Maven logging](#add-timestamps-to-maven-logging) + 2. [Add Maven profile](#add-maven-profiler) + 3. [Yourkit YouMonitor](#yourkit-youmonitor) +11. [Contact](#contact) +12. [👔 Process and Legal](#👔-process-and-legal) + 1. [Eclipse Development Process](#eclipse-development-process) + 2. [Eclipse Contributor Agreement](#eclipse-contributor-agreement) + ## Try SNAPSHOTs and report issues To enable SNAPSHOTs, make sure the following Maven plugin-repository is available to your build: https://repo.eclipse.org/content/repositories/tycho-snapshots/. @@ -51,7 +82,7 @@ Step-by-step instructions: 10. Once the _Executing startup task_ job is finished you should have all the Tycho and Tycho Extras projects imported into 2 working sets called _Tycho_ and _Tycho Extras_ . 11. Some Projects might still have errors. Select them (or all) and choose _Maven > Update Project.._ from the context menu. De-select _Clean projects_ in the shown dialog and press _OK_ to update the projects. After that, no more errors should be present. -### Manual setup +### Manual Setup The preferred and easier way is to follow the instructions above, but you could also setup your environment manually: @@ -71,9 +102,17 @@ Tycho has two types of tests: unit tests (locally in each module) and a global i Unit tests are preferred if possible because they are in general much faster and better targeted at the functionality under test. Integration tests generally invoke a forked Maven build on a sample project (stored under projects/) and then do some assertions on the build results. -### Tycho integration tests +### Tycho Integration Tests -The Tycho integration tests are located in the project `tycho-its`. To run all Tycho integration tests, execute `mvn clean install -f tycho-its/pom.xml`. To run a single integration test, select the test class in Eclipse and run it as ''JUnit Test''. +The Tycho integration tests are located in the project `tycho-its`. To run all Tycho integration tests, execute +``` +$ mvn clean install -f tycho-its/pom.xml` +``` +To run a single integration test, select the test class in Eclipse and run it as "JUnit Test", or run +``` +$ mvn clean verify -f tycho-its/pom.xml -Dtest=MyTestClass +``` +from the command line, replacing `MyTestClass` with the test class to run (without `.java`). _Background information on the Tycho integration tests_ @@ -81,7 +120,7 @@ The integration tests trigger sample builds that use Tycho. These builds expect Alternatively, e.g. if you are only interested in modifying an integration test and do not want to patch Tycho itself, you can configure the integration tests to download the current Tycho snapshot produced by the [Tycho CI builds](https://hudson.eclipse.org/tycho/view/CI). To do this, you need to edit the Maven settings stored in `tycho-its/settings.xml` and add the tycho-snapshots repository as described in [[Getting Tycho]]. (Advanced note: The integration tests can also be pointed to a different settings.xml with the system property `tycho.testSettings`.) -### Writing Tycho integration tests +### Writing Tycho Integration Tests The tycho integration tests are located in the [tycho-its](https://github.com/eclipse-tycho/tycho/tree/master/tycho-its) subfolder of the repository. Creating a new integration test usually includes the following steps: @@ -96,7 +135,12 @@ public void test() throws Exception { } ``` 3. You might want to check for additional constraints. See the [Verifier](https://maven.apache.org/shared/maven-verifier/apidocs/index.html) for available options. -4. If you don't want to run the full integration build you can simply go to the project directory and run `mvn clean verify -Dtycho-version=` to see the outcome of your created test. +4. If you don't want to run the full integration build you can simply go to the project directory and run + +``` +$ mvn clean verify -Dtycho-version= +``` +to see the outcome of your created test. #### Tips on the naming of integration tests @@ -104,82 +148,18 @@ public void test() throws Exception { The hardest part of writing Tycho integration tests is the naming. While names are mostly important for readability, there were also cases where the ID "feature" was used multiple times, and hence a test used the build result of a different integration test. Therefore, here are a few tips for writing good integration tests: -* Test project name: Although many existing tests have a bug number in the name, this is '''not''' the recommended naming scheme. Since integration tests can take some time to execute, it may be a good idea to test related things in one test.
So name the test projects in a way that they can be found, and that related tests are sorted next to each other, e.g. in the form <component>.<aspect>. +* Test project name: Although many existing tests have a bug number in the name, this is **not** the recommended naming scheme. Since integration tests can take some time to execute, it may be a good idea to test related things in one test.
So name the test projects in a way that they can be found, and that related tests are sorted next to each other, e.g. in the form <component>.<aspect>. * Package: Should be org.eclipse.tycho.test.<component> (without the aspect so that we don't get an excessive number of packages) * Test project groupIds: Should be tycho-its-project.<component>.<aspect> plus a segment for the reactor in case of multi-reactor tests. The groupId is particularly important if the test project is installed in the local Maven repository. Avoid `install`, use `verify` if possible. * Test project artifact ids have to be the same as the ID of the feature/bundle and need a unique prefix, e.g. the first letters of each segment of the project name. -## Advanced development tricks - -### Building Tycho against a locally built version of p2 - -Tycho makes heavy use of p2 functionality. Therefore it may be useful to try out patches of p2 without waiting for a new p2 release, or even just the next nightly build. With the following steps, it is possible to build Tycho against a locally built version of p2. - -1. Get the p2 sources (see [p2 project information](https://projects.eclipse.org/projects/rt.equinox.p2/developer)) -2. Make changes in the p2 sources, **(!) don't forget to increase the version of that bundle otherwise your changes will be overwritten with the current release version (!)** -3. Build the changed p2 bundles individually with mvn clean install -Pbuild-individual-bundles (see [Equinox/p2/Build](https://wiki.eclipse.org/Equinox/p2/Build) for more information) -4. Build at least the Tycho module tycho-bundles-external with mvn clean install - you should see a warning that the locally built p2 bundles have been used. -Then the locally built Tycho SNAPSHOT includes the patched p2 version. - -Note: Tycho always allows references to locally built artifacts, even if they are not part of the target platform. Therefore you may want to clear the list of locally built artifacts (in the local Maven repository in `.meta/p2-local-metadata.properties`) after you have finished your trials with the patched p2 version. - -### Running with a locally built version of the JDT compiler - -Tycho internally calls the Eclipse Java Compiler, therefore it might be useful to try your patches to ECJ without waiting for a new release, or even just the next nightly build. With the following steps, it is possible to run a Tycho build with a locally built version of ECJ; - -1. Get the sources from https://github.com/eclipse-jdt/eclipse.jdt.core -2. Make changes in the ECJ sources, **(!) don't forget to increase the version of that bundle otherwise your changes will be overwritten with the current release version (!)** -3. Build the `eclipse.jdt.core/org.eclipse.jdt.core` module with `mvn clean package -Pbuild-individual-bundles -Dtycho.localArtifacts=ignore -DskipTests` -4. Install the result in your local maven repository under a new version `mvn install:install-file -Dfile=/eclipse.jdt.core/org.eclipse.jdt.core/target/org.eclipse.jdt.core--batch-compiler.jar -DgroupId=org.eclipse.jdt -DartifactId=ecj -Dversion= -Dpackaging=jar` -5. Now edit the `pom.xml` of the project you'd like to test and either edit or insert -```xml - - org.eclipse.tycho - tycho-compiler-plugin - ${tycho-version} - - - org.eclipse.jdt - ecj - - - - -``` - -### Updating the Equinox and JDT dependencies of Tycho - -Tycho has Maven dependencies to Equinox and JDT, so these artifacts are used from the Maven Central repository. - -### Profiling the Tycho build - -To understand where the build spends most of its time, you can try the following approaches: - -#### Add timestamps to Maven logging - -You can [add a timestamp to each log line](https://blogs.itemis.com/en/in-a-nutshell-adding-timestamps-to-maven-log-output) produced by Maven. This is the easiest method, but you have to do the calculation of the runtime of different goals yourself. - -#### Add Maven profiler - -Download the [Maven profiler extension](https://github.com/jcgay/maven-profiler) and add it to your aggregator project. It will produce an HTML report for each goal. - -To install it, simply add an [extensions.xml file to your project aggregator](https://github.com/jcgay/maven-profiler#maven--33x) with the Maven coordinates of the profiler. That way Maven will automatically download the profiler during the build. - -To use the profiler, [set the system property](https://github.com/jcgay/maven-profiler#usage). - -#### Yourkit YouMonitor - -[Yourkit YouMonitor](https://www.yourkit.com/youmonitor/) (not to be confused with Yourkit Profiler) can be used to measure the build time steps. It reports the timing for Maven mojos, Ant goals, etc. You need to register it as a Java agent for your build. It allows easy comparison of multiple builds, therefore it's really nice for trying different optimizations and configurations. Be aware the free license is only available for local builds, not for CI servers. - -To get started with YouMonitor, you need to install and run the application. It will ask you for a repository, which is how you aggregate builds (e.g. use one repository per different project that you want to investigate). Afterward, select the [Monitoring in IDE or command line](https://www.yourkit.com/docs/youmonitor/help/ide_and_command_line.jsp) and use the button `Open Instructions`. That will show you the project and machine-specific argument which needs to be added to the Java command line. For example, if you want to profile tests, you might want to add it to the [argLine configuration of Tycho Surefire](https://www.eclipse.org/tycho/sitedocs/tycho-surefire-plugin/test-mojo.html#argLine). - ## 🏗️ Build & Test From the root directory of your local Tycho git-repository clone run the following Maven commands... * to check if the compilation and all tests succeed: * `mvn clean verify -Pits` * to install your version of Tycho into your local Maven repository (skips all tests for faster installation): - * `mvn clean install -DSkipTests` + * `mvn clean install -DskipTests` In order to test your changes of Tycho locally in a project-build, install your modified Tycho locally as described above and use the corresponding Tycho (probably snapshot) version in the project being build. @@ -223,11 +203,9 @@ Do not mix concerns in commits: have a commit do a single thing. This makes them ## Submit patch -As a GitHub pull request. +As a GitHub pull request. Create a branch off of `master` with a helpful name, like `issue__reproducer` if you are providing an integration test for an existing issue, or `compiler-plugin-bug` if you are fixing a bug with the compiler plugin. -## Contact - -Contact the project developers via the project's "dev" list: https://dev.eclipse.org/mailman/listinfo/tycho-dev +Create a branch off of master even for small bug fixes. Changes from `master` can be backported automatically to older versions, and it's important that master not miss any fixes that older versions have. See [Backporting](#backporting) for more information. ## Increasing versions @@ -260,14 +238,84 @@ If you choose one of the first options, backporting usually includes the followi 5. Look through the issues that were fixed after your target release and identify more items that seem useful and repeat with step 3. 6. Once there is a noticeable amount of things backported that could justify a release create an issue asking for a bugfix release to be performed. +## Advanced development tricks + +### Building Tycho against a locally built version of p2 + +Tycho makes heavy use of p2 functionality. Therefore it may be useful to try out patches of p2 without waiting for a new p2 release, or even just the next nightly build. With the following steps, it is possible to build Tycho against a locally built version of p2. + +1. Get the p2 sources (see [p2 project information](https://projects.eclipse.org/projects/rt.equinox.p2/developer)) +2. Make changes in the p2 sources, **(!) don't forget to increase the version of that bundle otherwise your changes will be overwritten with the current release version (!)** +3. Build the changed p2 bundles individually with mvn clean install -Pbuild-individual-bundles (see [Equinox/p2/Build](https://wiki.eclipse.org/Equinox/p2/Build) for more information) +4. Build at least the Tycho module tycho-bundles-external with mvn clean install - you should see a warning that the locally built p2 bundles have been used. +Then the locally built Tycho SNAPSHOT includes the patched p2 version. + +Note: Tycho always allows references to locally built artifacts, even if they are not part of the target platform. Therefore you may want to clear the list of locally built artifacts (in the local Maven repository in `.meta/p2-local-metadata.properties`) after you have finished your trials with the patched p2 version. + +### Running with a locally built version of the JDT compiler + +Tycho internally calls the Eclipse Java Compiler, therefore it might be useful to try your patches to ECJ without waiting for a new release, or even just the next nightly build. With the following steps, it is possible to run a Tycho build with a locally built version of ECJ; + +1. Get the sources from https://github.com/eclipse-jdt/eclipse.jdt.core +2. Make changes in the ECJ sources, **(!) don't forget to increase the version of that bundle otherwise your changes will be overwritten with the current release version (!)** +3. Build the `eclipse.jdt.core/org.eclipse.jdt.core` module with `mvn clean package -Pbuild-individual-bundles -Dtycho.localArtifacts=ignore -DskipTests` +4. Install the result in your local maven repository under a new version `mvn install:install-file -Dfile=/eclipse.jdt.core/org.eclipse.jdt.core/target/org.eclipse.jdt.core--batch-compiler.jar -DgroupId=org.eclipse.jdt -DartifactId=ecj -Dversion= -Dpackaging=jar` +5. Now edit the `pom.xml` of the project you'd like to test and either edit or insert +```xml + + org.eclipse.tycho + tycho-compiler-plugin + ${tycho-version} + + + org.eclipse.jdt + ecj + + + + +``` + +### Updating the Equinox and JDT dependencies of Tycho + +Tycho has Maven dependencies to Equinox and JDT, so these artifacts are used from the Maven Central repository. + +### Profiling the Tycho build + +To understand where the build spends most of its time, you can try the following approaches: + +#### Add timestamps to Maven logging + +You can [add a timestamp to each log line](https://blogs.itemis.com/en/in-a-nutshell-adding-timestamps-to-maven-log-output) produced by Maven. This is the easiest method, but you have to do the calculation of the runtime of different goals yourself. + +#### Add Maven profiler + +Download the [Maven profiler extension](https://github.com/jcgay/maven-profiler) and add it to your aggregator project. It will produce an HTML report for each goal. + +To install it, simply add an [extensions.xml file to your project aggregator](https://github.com/jcgay/maven-profiler#maven--33x) with the Maven coordinates of the profiler. That way Maven will automatically download the profiler during the build. + +To use the profiler, [set the system property](https://github.com/jcgay/maven-profiler#usage). + +#### Yourkit YouMonitor + +[Yourkit YouMonitor](https://www.yourkit.com/youmonitor/) (not to be confused with Yourkit Profiler) can be used to measure the build time steps. It reports the timing for Maven mojos, Ant goals, etc. You need to register it as a Java agent for your build. It allows easy comparison of multiple builds, therefore it's really nice for trying different optimizations and configurations. Be aware the free license is only available for local builds, not for CI servers. + +To get started with YouMonitor, you need to install and run the application. It will ask you for a repository, which is how you aggregate builds (e.g. use one repository per different project that you want to investigate). Afterward, select the [Monitoring in IDE or command line](https://www.yourkit.com/docs/youmonitor/help/ide_and_command_line.jsp) and use the button `Open Instructions`. That will show you the project and machine-specific argument which needs to be added to the Java command line. For example, if you want to profile tests, you might want to add it to the [argLine configuration of Tycho Surefire](https://www.eclipse.org/tycho/sitedocs/tycho-surefire-plugin/test-mojo.html#argLine). + +## Contact + +Contact the project developers via the project's "dev" list: https://dev.eclipse.org/mailman/listinfo/tycho-dev. + +You can also post questions in the [Discussions](https://github.com/eclipse-tycho/tycho/discussions) section of this repository. + ## 👔 Process and Legal -## Eclipse Development Process +### Eclipse Development Process This Eclipse Foundation open project is governed by the Eclipse Foundation Development Process and operates under the terms of the Eclipse IP Policy. -## Eclipse Contributor Agreement +### Eclipse Contributor Agreement Before your contribution can be accepted by the project team contributors must electronically sign the Eclipse Contributor Agreement (ECA): https://www.eclipse.org/legal/ECA.php