Skip to content

Developer's Guide

Jump to bottom
Jiaqi Guan edited this page Sep 21, 2018 · 11 revisions

The easiest way to get and use ParSeq is with a dependency management tool, such as Gradle, Ivy or Maven. These and similar tools will automatically get all required dependencies for ParSeq.

You can also download the binaries, but you must also download ParSeq's dependencies (see the pom for a list of dependencies).

Lastly, if you want the very latest code or want to make changes to ParSeq, you can build ParSeq from source.

Dependency Management Integration

ParSeq releases are hosted on the Maven Central Repository. We provide steps for integration with 3 common dependency management tools in the following subsections.

Gradle Integration

To integrate with an Gradle project, add the snippet below to your build.gradle file. Change the version value to the release you intend to consume.

dependencies {
   compile group: 'com.linkedin.parseq', name: 'parseq', version:'3.0.0'
}

Ivy Integration

To integrate with an Ivy project, add the code block below to your ivy file. Make sure to update *rev* to the release you intend to consume (for example: 2.0.5).

<dependency org="com.linkedin.parseq" name="parseq" rev="*rev*" />

Maven Integration

To integrate with a Maven project, add the code block below to your pom file. Make sure to update *version* to the release you intend to consume (for example: 2.0.5).

<dependency>
    <groupId>com.linkedin.parseq</groupId>
    <artifactId>parseq</artifactId>
    <version>2.0.5</version>
</dependency>

Building ParSeq from Source

To build ParSeq from source, download and install the following build pre-requisites:

  • Java JDK 1.8.
  • Optionally Gradle 4.8 or later. Although ParSeq has Gradle wrapper and you needn't install any Gradle stuff, to install Gradle would make run tasks more easier.
  • Optionally node.js and npm for trace visualization. Since ParSeq use Gradle plugin to trigger npm run commands. So if you don't want to install Node.js locally, you could leverage this plugin to write your own Gradle task to install package and run javascript files. For all already existing packages and dependencies, you could build them without installing any Node.js related tools.
  • Optionally [GPG] for releasing to Maven Central Repository.

To build ParSeq

  1. Clone the ParSeq repository: git clone git://github.com/linkedin/parseq.git

  2. Use ./gradlew clean build to verify that source code can be built and passes all unit tests.

  3. If you just want to build ParSeq subproject(modules) instead of the whole project:

# go to one of ParSeq subproject directory
cd parseq/subprojects/parseq-restli-client
# build and test parseq contrib
../.././gradlew clean build
 
# (alternative) you needn't to switch the directory and can just stay in the root directory
./gradlew :parseq-restli-client:build
  1. Use ./gradlew uploadArchives -Prelease to build the ParSeq library into the parseq/build directory.
cd parseq
# go to your parseq multi-product directory
cd parseq_trunk/parseq
# Release artifacts to remote maven repo
./gradlew clean uploadArchives -Prelease -PossRelease
# the "release" property control whether the version is a SNAPSHOT
# the "ossRelease" property control whether publish the artifacts to public

# (option)Release snapshot artifacts to local repo, it's in "parseq/build" directory
./gradlew clean uploadArchives

Generate IDE Project

Open "parseq" project in IDEA, usually idea will take care of loading all the dependencies. If not, you can do following steps. Make sure you are using the 1.8.0_121 JDK.

cd parseq
./gradlew cleanIdea
./gradlew idea

Edit CHANGELOG

The CHANGELOG file in the root git directory needs to be manually maintained. It contains a list a versions with changes in each version. Unlike many other projects, not every commit will have a new version published.

Remember, the top version is always the next version to be released. In the following example, version 2.9.9 hasn't been released yet.

2.9.9
-----
Description of issue 99999
 
2.9.8
-----
Description of issue 99998
 
Description of issue 99997

Right after releasing a new version, there is an empty version entry for the next version at the top, as seen below.

2.9.10
-----
  
2.9.9
-----
Description of issue 99999
 
2.9.8
-----
Description of issue 99998
 
Description of issue 99997

Contribute Code

# go to your git root directory
cd parseq
# Starting from master, this creates a new branch AND switches to it
git checkout -b my-feature
# work work work
git commit
# ready to create a pull request
git push origin my-feature
# go to https://github.com/linkedin/parseq to create a pull request by comparing your branch "my-feature" with "master" branch
......
# Incorporate feedback and update pull request
......
# Check / update CHANGELOG.md by adding changelog under current version (yet to be released)
vim CHANGELOG.md
# Parseq owner will merge your pull request into master
......
Clone this wiki locally