Skip to content

Latest commit

 

History

History
113 lines (71 loc) · 5.68 KB

CONTRIBUTING.md

File metadata and controls

113 lines (71 loc) · 5.68 KB
Raw

Contribution guide

Want to contribute? Great! We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples... But first, read this page (including the small print at the end).

Legal

All original contributions to Kogito are licensed under the ASL - Apache License, version 2.0 or later, or, if another license is specified as governing the file or directory being modified, such other license.

Issues

Kogito uses JIRA to manage and report issues.

If you believe you found a bug, please indicate a way to reproduce it, what you are seeing and what you would expect to see. Don't forget to indicate your Kogito, Java, Maven, Quarkus/Spring, GraalVM version.

Checking an issue is fixed in master

Sometimes a bug has been fixed in the master branch of Kogito and you want to confirm it is fixed for your own application. Testing the master branch is easy and you have two options:

If you are interested in having more details, refer to the Build section and the Usage section.

Creating a Pull Request (PR)

To contribute, use GitHub Pull Requests, from your own fork.

  • PRs should be always related to an open JIRA issue. If there is none, you should create one.

  • Try to fix only one issue per PR.

  • Make sure to create a new branch. Usually branches are named after the JIRA ticket they are addressing. E.g. for ticket "KOGITO-XYZ An example issue" your branch should be at least prefixed with KOGITO-XYZ. E.g.:

      git checkout -b KOGITO-XYZ
  # or
  git checkout -b KOGITO-XYZ-my-fix

  • When you submit your PR, make sure to include the ticket ID, and its title; e.g., "KOGITO-XYZ An example issue".

  • The description of your PR should describe the code you wrote. The issue that is solved should be at least described properly in the corresponding JIRA ticket.

  • If your contribution spans across multiple repositories, use the same branch name (e.g. KOGITO-XYZ) in each PR so that our CI (Jenkins) can build them all at once.

  • If your contribution spans across multiple repositories, make sure to list all the related PRs.

Coding Guidelines

We decided to disallow @author tags in the Javadoc: they are hard to maintain, especially in a very active project, and we use the Git history to track authorship. GitHub also has this nice page with your contributions.

Tests and Documentation

Don't forget to include tests in your pull requests, and documentation (reference documentation, javadoc...). Guides and reference documentation should be submitted to the Kogito Docs Repository. If you are contributing a new feature, we strongly advise submitting an Example.

Code Reviews and Continuous Integration

All submissions, including those by project members, need to be reviewed by others before being merged. Our CI, Jenkins, should successfully execute your PR, marking the GitHub check as green.

Feature Proposals

If you would like to see some feature in Kogito, start with an email to our mailing list or just pop into our Zulip chat and tell us what you would like to see.

Great feature proposals should include a short Description of the feature, the Motivation that makes that feature necessary and the Goals that are achieved by realizing it. If the feature is deemed worthy, then an Epic will be created.

Setup

If you have not done so on this machine, you need to:

  • Install Git and configure your GitHub access
  • Install Java SDK (OpenJDK recommended)
  • For Native Image, follow Quarkus instructions at GraalVM

Docker is not strictly necessary, but it is a required to run some of the integration tests. These tests can be skipped (see the Build section), but we recommend to install it to run these tests locally.

Build

  • Clone the repository, navigate to the directory, invoke ./mvnw clean install -DskipTests -DskipITs from the root directory.
git clone https://github.com/kiegroup/kogito-runtimes.git
cd kogito-runtimes
./mvnw clean install -DskipTests -DskipITs 
# Wait... success!

This build skipped all the tests:

  • -DskipTests skips unit tests
  • -DskipITs skips integration tests

By removing the flags, you will run the corresponding tests. It will take much longer to build but will give you more guarantees on your code.

Usage

After the build is successful, the artifacts are available in your local Maven repository.

Test Coverage

Kogito uses Jacoco to generate test coverage. If you would like to generate the report run mvn clean verify -Ptest-coverage. The code coverage report will be generated in target/site/jacoco/.

The small print

This project is an open source project, please act responsibly, be nice, polite and enjoy!