Skip to content

Latest commit

 

History

History
171 lines (122 loc) · 10.8 KB

CONTRIBUTING.md

File metadata and controls

171 lines (122 loc) · 10.8 KB
Raw

On this page, we describe the development process that all team members contributing to TestRoots must adhere to.

Getting started

This section gives a brief overview of the steps necessary to have a working development environment for WatchDog. This should work for Linux, Windows, and MacOs.

  1. Install Git. Install Eclipse. Install IntelliJ. Details under section IDE on this page. (Optional: Install Eclipse plugins.)
  2. Install Maven.
  3. Clone Git repository branch master.
  4. Run ./intellij/fetchidea.sh to obtain a local version of IntelliJ for the project.
  5. Setup the WatchDog project for IntelliJ and Eclipse (see later steps)
  6. Install WatchDog for IntelliJ and Eclipse and set it up at least for your WatchDog development workspaces.

Study the section "Workflow" to get to know how we develop.

IDE

WatchDog is an Eclipse and IntelliJ plugin. It is built and written for Java 1.8. Following the "eat your own dog food" principle, all developers should have WatchDog installed and running in their development instance of the IDE.

In this section, we describe how WatchDog needs to be setup. It is important to have both plugins and development environments set-up to catch potential induced problems even if you only intend to modify one.

Eclipse

  1. Download Eclipse.
  2. Install the PDE plugin (https://marketplace.eclipse.org/content/eclipse-pde-plug-development-environment)
  3. Import Maven -> Existing Maven project and select the watchdog root folder. Import all subprojects except the IntelliJ folder (or remove it later if you have imported it, it will give build errors).
  4. Optional: For Maven IDE support, you need m2e for IDE-supported POM.xml-file editing. As we are also using Tycho, you need the tycho configuration connector in m2e's marketplace.
  5. Optional: If your run configuration complains about unrecognized options, make sure to remove all inclusions of --add-modules=ALL-SYSTEM in your VM arguments. These are added incorrectly by PDE and won't work on a JDK 1.8 or lower.
  6. Select the correct target platform:
    1. Window -> Preferences -> Plug-in Development -> Target Platform
    2. Select the target platform from /watchdog/eclipse/platform/watchdog.eclipse.platform.target

IntelliJ

  1. Download the free IC edition
  2. Install the "Intellij plugin development with Maven"-plugin from https://plugins.jetbrains.com/plugin/7127-intellij-plugin-development-with-maven
  3. Start by Importing a project and selecting pom.xml in the root folder of the repository. When importing, you can step through with the defaults. The process of fetching dependencies by IntelliJ can take a while.
  4. Install the IntelliJ SDK:
    1. Run intellij/fetchIdea.sh
    2. Add the local version of the IntelliJ SDK to your IntelliJ running per instructions of https://www.jetbrains.com/help/idea/configuring-intellij-platform-plugin-sdk.html
    3. In Project Structure, go to Modules -> watchdog -> intellij.
    4. On the tab "dependencies", click new module SDK
    5. Select the IntelliJ SDK from the local version available in intellij/build_cache/idea-IU-***
  5. Create a new Run Configuration:
    1. Run -> Edit Configurations -> New -> Plugin.
    2. Classpath should point to watchdog.intellij
    3. JRE should be the local version of IntelliJ that exists in intellij/build_cache/
  6. Double check that in Project Structure -> Modules -> watchdog -> intellij -> Plugin Deployment, the Path to META-INF/plugin.xml is watchdog/intellij/resources/. You can safely delete the intellij/META-INF/ folder now.
  7. Install the downloaded CheckStyle plugin from the build_cache:
    1. Unzip the CheckStyle zip in build_cache/
    2. Add the CheckStyle plugin to the IntelliJ SDK you downloaded per the instructions of https://www.jetbrains.org/intellij/sdk/docs/basics/plugin_structure/plugin_dependencies.html You need to select the CheckStyle jar from build_cache/Checkstyle-IDEA/lib/checkstyle-idea-****.jar
  8. Open WatchDogStartup.java and click on the run configuration. A runtime workbench of IntelliJ should pop up with a local version of WatchDog running.
  9. (Optional, but recommended to test Checkstyle warnings) In the runtime workbench, install the Checkstyle Plugin via Settings > Plugins > Browse repositories ... and searching for "CheckStyle-IDEA". The plugin comes from https://infernus.org/ and https://github.com/jshiell/checkstyle-idea

Subprojects

Using either IDE, you will import multiple subprojects. This section explains the structure of this project with its subprojects and their corresponding purpose.

  • core

    Core contains all code that is shared between all custom IDE implementations. It mostly focuses on the data format, its storage method and the network protocols.

  • eclipse

    Project that contains several other subprojects all related to the Eclipse plugin. Most of these projects are necessary to generate a correct OSGi bundle that can be consumed by Eclipse.

    • plugin

      The plugin contains the actual implementation of the plugin. It augments core by all custom logic to wire into the Eclipse editor. You can start the plugin by running nl.tudelft.watchdog.eclipse.Activator with Run As Eclipse Application.

    • tests

      An Eclipse plugin test project that runs an editor and instruments the Eclipse plugin either directly or indirectly.

    • platform

      To correctly build both the plugin and its tests, the plugin requires a target platform which specify its dependencies. For more information, read this documentation page.

    • features

      Based on the plugin and the target platform, both the core and eclipse.plugin need to build a feature that can be consumed by Eclipse OSGi. The features do not contain any code implementation, rather they contain a feature.xml and build.properties to configure the Eclipse OSGi dependencies.

    • p2updatesite

      Both features are then grouped into one artifact called a repository. This repository is the final output that will be uploaded to the Eclipse updatesite such that users can install the plugin.

  • intellij

    The plugin implementation that augments core into the IntelliJ Idea editor. You can start the plugin by using the run configuration as explained in the IntelliJ section down below.

  • server

    A Ruby server that processes user/project creation as well as any other data we require and inserts it into a Mongo database. This server therefore requires Mongo to be running locally on your machine.

Install WatchDog

To install WatchDog locally, follow the process described on http://testroots.org/testroots_watchdog.html. There are two additional options that might be interesting to you:

  1. To install your home-built version of WatchDog, click on Local. Once you ran step (4), your local build is located under <Git repository>/WatchDogEclipse/p2updatesite/target/repository and <Git repository>/WatchDogIntelliJ/WatchDog/WatchDog.zip. Add this folder/zip as a plugin. Follow the instructions in the dialogue and restart Eclipse to activate WatchDog. or
  2. The latest development build is stored under http://www.watchdog.testroots.org/updatesite_snaphsot (checked-out automatically and built on master).

Workflow

  1. If you are not a core committer: Fork the WatchDog repo.
  2. Create a new issue in issue tracker https://github.com/TestRoots/watchdog/issues.
  3. Create local branch in git: git branch your_branch
  4. Make your modifications. Every commit must reference the issue id from (1).
  5. Make sure the project builds correctly through travis_build.sh.
  6. Once your work is complete, push the local branch to remote: git push --set-upstream origin your_branch
  7. File a pull request on the remote branch for integration to master.

Issue Task Manager

We manage our issues and tasks in Github. Every commit must reference an issue on Github in its commit message, like so #(issueId). If a commit closes an issue, this can be done via fixes #(issueId). Non-technical tasks can and should also be managed via Github's issue manager.

Build dependencies

Eclipse plugins are OSGI bundles. As such, they are Manifest-first in the maven build process and therefore cannot use Maven's pom-first dependency resolution mechanism. Therefore, we manage our dependencies manually in the lib folder.

Continuous Integration

We use Travis CI as our build server. It can be reached under https://travis-ci.org/TestRoots/watchdog.

At the moment, our build status is .

Testing

Being quality-driven, WatchDog makes use of unit testing. the JUnit tests are collected in an Eclipse fragment project, complementing the original Eclipse IDE plugin.

Static Analysis

In WatchDog, we heavily rely on static analysis to ensure product quality.

Code Review

Every change must undergo code review before acceptance into the main branch. This is done by developing on your own local branch, and then filing a pull request for the branch. Another member of the team will review the pull request, and give you feedback.

Automated Static Analysis

We use a number of configured automated static analysis tools such as FindBugs, Codeclimate and Teamscale to monitor the quality of our product. We use Teamscale as a dashboard to monitor our general product quality. Register yourself here: https://demo.teamscale.com The number of findings in our product should be kept as low as possible.

Deployment

The Eclipse IDE updatesite needs to be signed before deployment. Deployment is then a simple mv of directories on our server. For IntelliJ, the plugin repository needs to be updated.

Creating a new release

Builds are created automatically every hour on the server, and on-demand on the CI. Creating a new relase involves increasing the version number in several places. To make things easier, you can use this command (to bump from 3.1.0 to 3.2.0 in this example): find . -type f ! -path "*.git*" ! -path "*/libs/*" ! -path "*/target/*" ! -path "*/build_cache/*" | xargs sed -i 's/3\.1\.0/3\.2\.0/g' Please check the diff before committing!

  1. Export ZIP for IntelliJ via Build > Prepare Plugin Module ... Upload the generated ZIP to the IntelliJ repository

  2. Sign the generated Eclipse packages

  3. Update update_site on server

  4. Restart server (for updated version string)

Sign it

We only sign Eclipse releases.

  1. Go to cd eclipse/p2updatesite/target/repository/
  2. Make sure export JAVA_HOME=/usr/lib/jvm/java-8-oracle
  3. Eplace STOREPASS and KEYPASS and run find . -type f -follow -print | xargs -i jarsigner -keystore "$JAVA_HOME/jre/lib/security/cacerts" -storepass "STOREPASS" -keypass "KEYPASS" -verbose '{}' 72a9b5399b49480482699d126b4ee9e5
  4. Update Eclipse Updatesite on server
  5. Git pull and Restart server
  6. Update Eclipse Marketplace
  7. Upload to IJ repository