The build bootstrap contains the parent pom, guidelines and scripts for Drools, jBPM and OptaPlanner.
If you want to build or contribute to a kiegroup project, read this document.
This document will save you and us a lot of time by setting up your development environment correctly. It solves all known pitfalls that can disrupt your development. It also describes all guidelines, tips and tricks. If you want your pull requests (or patches) to be merged into master, please respect those guidelines.
If you are reading this document with a normal text editor, please take a look at the more readable formatted version.
If you discover pitfalls, tips and tricks not described in this document, please update it using the markdown syntax.
If you don't want to contribute to this project and you know git and maven, these build instructions should suffice:
To build 1 repository, for example
$ git clone [email protected]:kiegroup/drools.git $ cd drools $ mvn clean install -DskipTests
To build all repositories:
$ git clone [email protected]:kiegroup/droolsjbpm-build-bootstrap.git $ droolsjbpm-build-bootstrap/script/git-clone-others.sh $ droolsjbpm-build-bootstrap/script/mvn-all.sh clean install -DskipTests
If you want to contribute to this project, read the rest of this file!
Install git in your OS:
Check if git is installed correctly.
$ git --version git version 2.21.2
Configure git correctly:
$ git config --global user.name "My Full Name" $ git config --global user.email [email protected] $ git config --global -l user.name= user.email=
user.nameis your full name, not your username.
user.emailshould match an email address of your github account.
Get a github account
To learn more about git, read the free book Pro Git.
Because you'll probably want to change our code, it's recommended to fork our code before cloning it, so it's easier to share your changes with us later. For more info on forking, read GitHub's help on forking.
First fork the repository you want to work on, for example
Surf to the blessed repositories on github and log in.
droolsin this case).
Surf to the specific repository (drools)
Click the top right button Fork
Note: by forking the repository, you can commit and push your changes without our consent and we can easily review and then merge your changes into the blessed repository.
Clone your fork locally:
# First make a directory to hold all the kiegroup projects $ mkdir kiegroup $ cd kiegroup
Then clone the repository you want to clone.
$ git clone [email protected]:MY_GITHUB_USERNAME/drools.git $ cd drools $ ls
By default you will be looking at the sources of the master branch, which can be very unstable.
Use git checkout to switch to a more stable branch or tag:
$ git checkout # i.e git checkout 7.33.x
Add the blessed repository as upstream (if you've directly cloned the blessed repository, don't do this):
$ git remote add upstream [email protected]:kiegroup/drools.git $ git fetch upstream
First make a topic branch:
$ git checkout master $ git checkout -b myFirstTopic
masterbranch: keep it equal to
Make changes, run, test and document them, then commit them:
$ git commit -m "Fix typo in documentation"
Push those commits on your topic branch to your fork
$ git push origin myFirstTopic
Get the latest changes from the blessed repository
Set your master equal to the blessed master:
$ git fetch upstream $ git checkout master # Warning: this deletes all changes/commits on your local master branch, but you shouldn't have any! $ git reset --hard upstream/master
Start a new topic branch and set the code the same as the blessed master:
$ git fetch upstream && git checkout -b mySecondTopic && git reset --hard upstream/master
If you have a long-running topic branch, merge master into it:
$ git fetch upstream $ git merge upstream/master
If there are merge conflicts:
$ git mergetool $ git commit
$ git status $ gedit conflicted-file.txt $ git add conflicted-file.txt $ git commit
Many people get confused when a merge conflict occurs, because you're in limbo. Just fix the merge conflicts and commit (even if the git seems to contain many files), only then is the merge over. Then run
git logto see what happened. The many files in the merge conflict resolving commit are a side effect of non-linear history.
You may delete your topic branch after your pull request is closed (first one deletes remotely, second one locally):
$ git push origin :myTopicBranch $ git branch -D myTopicBranch
Tips and tricks
To see the details of your local, unpushed commits:
$ git diff origin...HEAD
To run a git command (except clone) over all repositories (only works if you cloned all repositories):
$ cd ~/projects/kiegroup $ droolsjbpm-build-bootstrap/script/git-all.sh push
git-all.shscript is working directory independent.
Linux tip: Create a symbolic link to the
git-all.shscript and place it in your
PATHby linking it in
$ ln -s ~/projects/kiegroup/droolsjbpm-build-bootstrap/script/git-all.sh ~/bin/kiegroup-git
For command line completion, add the following line in
$ complete -o bashdefault -o default -o nospace -F _git kiegroup-git
A pull request is like a patch file, but easier to apply, more powerful and you'll be credited as the author.
Creating a pull request
Push all your commits to a topic branch on your fork on github (if you haven't already).
Surf to that topic branch on your fork on github.
Click the button Pull Request on the top of the page.
Accepting a pull request
Click the button Merge help on the bottom of the page and follow the instructions of github to apply those changes on the blessed master.
If the change being proposed is affecting more than a single repository, it will require creating a pull request for each of the repositories being affected; in this case, it is required for the topic branch to share the same name across all pull requests, in order for the CI build tool to include the necessary dependencies while performing the build with the proposed change. It is also highly recommended to use the github Autolinked references in the pull request comments, in order to make these dependencies explicit and emphasized during code reviews.
All projects use Maven 3 to build all their modules.
apt-getversion of maven is probably not up-to-date enough.
Linux trick to easily upgrade to future versions later:
Create a version-independent link:
$ cd ~/opt/build/ $ ln -s apache-maven-3.5.2 apache-maven
Next time you only have to remove the link and recreate the link to the new version.
Add this to your
export M3_HOME="~/opt/build/apache-maven" export PATH="$M3_HOME/bin:$PATH"
Give more memory to maven:
Give more memory to maven, so it can build the big projects too:
Open menu Configuration screen, menu item System, tab Advanced, button environment variables:
set MAVEN_OPTS="-Xms256m -Xmx1024m"
Check if maven is installed correctly.
$ mvn --version Apache Maven 3.5.2 (...) Java version: 1.8.0_112
Note: the enforcer plugin enforces a minimum maven and java version.
Go into a project's base directory, for example
$ cd ~/projects/kiegroup $ ls
the repositories displayed should be like listed here. repository_list
shell $ cd drools $ ls ... drools-core drools-cdi pom.xml ...
Notice you see a
pom.xmlfile there. Those
pom.xmlfiles are the heart of Maven.
Run the build:
$ mvn clean install -DskipTests
The first build will take a long time, because a lot of dependencies will be downloaded (and cached locally).
It might even fail, if certain servers are offline or experience hiccups. In that case, you 'll see an IO error, so just run the build again.
If you consistently get
Could not transfer artifact ... Connection timed outand you are behind a non-transparent proxy server, configure your proxy server in Maven.
After the first successful build, any next build should be fast and stable.
Try running a different profile by using the option
$ mvn clean install -DskipTests -Dfull
There are 3 profile activation properties:
full: Slow, but builds everything (including documentation). Used by Jenkins and during releases.
productized: activates branding changes for productized version
To run a maven build over all repositories (only works if you cloned all repositories):
$ cd ~/projects/kiegroup $ droolsjbpm-build-bootstrap/script/mvn-all.sh -DskipTests clean install
mvn-all.shscript is working directory independent.
You can use
mvn-all.shto compile a specific repository and all repositories that your target repository depends on. This is done using the
--target-repooption which will invoke
repo-dep-tree.plscript to discover cross-repository project dependencies. Use
--repo-listto specify custom list of repositories. These options work for
Warning: The first
mvnbuild of a day will download the latest SNAPSHOT dependencies of other kiegroup projects, unless you build all those kiegroup projects from source. Those SNAPSHOTS were build and deployed last night by Jenkins jobs.
If you haven't pulled all changes today, this is probably a bad thing: you 're probably not ready to deal with those new snapshots.
In that case, add
--no-snapshot-updates) to the
mvncommand to avoid downloading those snapshots:
$ mvn clean install -DskipTests -nsu
Note that using
-nsuwill also make the build faster.
$ cd ~/projects/kiegroup/drools $ mvn test [-Dtest=ATestClassName]
JaCoCo plugin allows to measure code-coverage for any child of droolsjbpm-build-bootstrap. The check binds to the verify phase and for the plugin to run, the code-coverage profile has to be enabled.
From the module/project folder run command:
$ mvn clean verify -Pcode-coverage
The coverage report is then generated in ./target/site/jacoco/index.html
Mutation coverage is used to measure how good the tests are at making assertions about the tested code. It is a good idea to check the mutation coverage of tests added together with any changes, be it a newly developed feature or a bug fix. Code coverage is analyzed for free as part of the mutation analysis.
To analyze the complete module:
$ mvn verify -Dmutation-coverage
To limit analyzed classes to a sub-package:
$ mvn verify -Dmutation-coverage -DtargetClasses=org.drools*
The HTML report will be stored in
local/pit-reports/directory. Currently, it is not possible to get a report aggregated over multiple modules. Learn more about using Pitest.
To deploy snapshots and releases to nexus, you need to add this to the file
... jboss-snapshots-repository jboss.org_username jboss.org_password jboss-releases-repository jboss.org_username jboss.org_password ...
Furthermore, you'll need nexus rights to be able to do this.
More info in the JBoss.org guide to get started with Maven.
Any dependency used in any KIE project must fulfill these hard requirements:
The dependency must have an Apache 2.0 compatible license.
Avoid: EPL, LGPL
Forbidden: no license, GPL, AGPL, proprietary license, field of use restrictions ("this software shall be used for good, not evil"), ...
To check the ALS compatibility license please visit these links:Similarity in terms to the Apache License 2.0 How should so-called "Weak Copyleft" Licenses be handled
Any version used must be in the repository Maven Central and/or JBoss (Nexus) Public repository group
Workaround to still use a great looking jar as a dependency:
The dependency must be able to run on any JVM 1.8 and higher.
Do not release the dependency yourself (by building it from source).
Why? Because it's not an official release, by the official release guys.
No security issues (CVE's) reported on that version of the dependency
The sources are publicly available
The dependency needs to use reasonable build system
Any dependency used in any KIE project should fulfill these soft requirements:
Edit dependencies in kie-parent.
Prefer dependencies with the groupId
org.jboss.specover those with the groupId
javax.*are unreliable and are missing metadata. No one owns/maintains them consistently.
org.jboss.specare checked and fixed by JBoss.
Only use dependencies with an active community.
Less is more: less dependencies is better. Bloat is bad.
Try to use existing dependencies if the functionality is available in those dependencies
poiis already a KIE dependency
Do not use fat jars, nor shading jars.
There are currently a few dependencies which violate some of these rules. If you want to add a dependency that violates any of the rules above, get approval from the project leads.
Some modules include Protobuf files (like drools-core and jbpm-flow). Every time a .proto file is changed, the java files have to be regenerated. In order to do that, on the module that contains the files to be regenerated, execute the following command:
$ mvn exec:exec -Dproto
After testing the regenerated files, don't forget to commit them.
IMPORTANT: before trying to regenerate the protobuf java files, you must install the protobuf compiler (protoc) in your machine. Please follow the instructions. You can download it from here: https://developers.google.com/protocol-buffers/docs/downloads.
For Linux/Mac, you have to compile it yourself as there are no binaries available. Follow the instructions in the README file for that.
To develop a great project as a team, we need to communicate efficiently as a team.
Fixing a community issue in JIRA:
Fix the issue and push those changes to the appropriate branch(es) on github.
Change the Status to
Resolveduntil the PR gets merged. Link the PR to the JIRA issue and wait till someone reviews the changes.
Closed. Or we bulk change it to
Closedafter a year.
Subscribe to the Drools Development Google Group and check it daily.
Subscribe to the RSS feeds.
Prefer an RSS reader which shows which RSS articles you've already read, such as:
Subscribe to jira issue changes:
Subscribe to github repository commits:
Join us on Zulip: Chat
Optionally install a DocBook editor to write documentation more comfortably, such as:
Click tree item Global
Click tree item Format
Click tree item Save
Checkbox Before saving, make a backup copy of the file:
To generate the html and pdf output run maven with
$ cd kiegroup $ cd optaplanner/optaplanner-docs $ mvn clean install -Dfull ... $ firefox target/docbook/publish/en-US/html_single/index.html
The Drools Expert manual uses railroad diagrams.
These are generated from a BNF file into images files with the application Ebnf2ps, Automatic Railroad Diagram Drawing
Why do you not accept
@authorlines in your source code?
Because the author tags in the java files are a maintenance nightmare
Because the author tags promote code ownership, which is bad in the long run.
If people work on a piece they perceive as being owned by someone else, they tend to:
For more motivation, see this video on How to get a healthy open source project?
Credit to the authors is given:
on the blog
with Open Hub which also has statistics