Skip to content

Latest commit

 

History

History
91 lines (70 loc) · 4.86 KB

CONTRIBUTING.md

File metadata and controls

91 lines (70 loc) · 4.86 KB
Raw

Contributing to Devhub

Devhub is organized in three components: devhub-server, git-server and build-server. Both the git-server and git-server expose REST APIs, for which a Java client interfaces are available. This is the repository for devhub-server.

Clone Devhub

The web dependencies (jQuery, Highlight.js, Bootstrap and Octicons) are loaded through submodules. After cloning the repository, you have to initialize these submodules.

git clone [email protected]:devhub-tud/devhub.git
git submodule init
git submodule update

Dependencies

  • Requires Maven 3.2 or higher, tested on Apache Maven 3.2.1 and 3.3.3.

Setting up your IDE

These steps were only tested for Eclipse and IntelliJ. To successfully run and test Devhub, a couple of steps should be followed to setup various dependencies and configurations.

  1. Fork the Devhub repository.
  2. Open the preferred IDE.
  3. Import the project as Maven project.
  4. Make sure that JDK 1.8 is being used for building Devhub.
  5. Run mvn generate-resources, this command should create various classes in target/metamodel.
  6. (For Eclipse) Set target/metamodel as source directory in the IDE. You can do this under Properties > Build Path). Sometimes it is required to first remove the folder, and then include it again.
  7. Run mvn compile, this compiles all application sources.
  8. Install Project Lombok.
    • For Eclipse follow these steps:
      1. Close Eclipse.
      2. Run the following JAR: .m2/repository/org/projectlombok/lombok/LATEST_LOMBOK_VERSION/lombok-LATEST_LOMBOK_VERSION.jar.
      3. The installation will provide the required steps to attach Lombok to Eclipse.
    • For IntelliJ follow these steps:
      1. "File"
      2. "Settings..."
      3. "Plugins"
      4. "Browse repositories..."
      5. Search for "lombok"
      6. Install "Lombok Plugin"

When the JPA plugin for Eclipse generates a lot of false errors, you can disable the validation under Preferences > Validation > JPA Validator.

Running the webtests

If you want to run the integration tests (which are the webtests), run the following command: mvn integration-test

For this, you will need to download a separate Chrome driver to run the test in a browser. You can find the driver at https://sites.google.com/a/chromium.org/chromedriver/downloads

Code Formatting

We do not write getters/setters and equals/hashcode implementations ourselves, but instead use the Lombok @Data and @EqualsAndHashcode annotations for that. Prevent overuse of Lombok, try to limit it to JPA classes and Jackson models.

Schema changes

We use Liquibase to perform the required schema changes in deployment. When a schema update is required for your changes, add a new entry at the bottom of the changelog.xml file. Do NOT alter existing changelog entries.

Less CSS changes

We use Less in order to generate CSS. The Less is transformed to CSS using the lesscss-maven-plugin. You can recompile the less file using mvn lesscss:compile. There is no need to restart the Devhub server afterwards.

Running Devhub

In the test source folder (src/test) you will find DevhubInMockedEnvironment. It uses almost the same bindings as Devhub in production, but with small modifications:

  • A temporary embedded database (H2) is used
  • The temporary embedded database is filled with data from the Bootstrapper, which parses a JSON configuration file (simple-environment.json by default).
  • The authentication does not fall back to LDAP, but only checks against the values in the database.
  • Instead of an actual git-server, it uses the git server classes against local file based repositories.

Using a real Git server

First start up a real Git server. In the git-server repository we can find a vagrantfile file which can be used to set up a Gitolite VM. Gitolite is the actual Git daemon we use. In order to configure a Virtual Machine from a vagrantfile, you need to have VirtualBox and Vagrant installed.

cd git-server
vagrant up
java -jar git-server/target/git-server-distribution/git-server/git-server.jar

The GitServerClientImpl connects to the address read from the config.properties file (default: http://localhost:8081).

Further reading

Before contributing to Devhub it's hugely recommended to read upon JAX-RS (we use the Resteasy implementation), JPA (we use Hibernate), Freemarker and Google Guice dependency injection.