If either of the two badges above are not green, please get in contact with engineering: some document might no longer be aligned.
Kogito is a cloud-native business automation technology for building cloud-ready business applications. Kogito includes components that are based on well-known business automation projects in the Knowledge Is Everything (KIE) community, specifically Drools, jBPM, and OptaPlanner, to offer dependable, open source solutions for business rules, business processes, and constraint solving.
As a Kogito user, developer, or technical writer, you can contribute to Kogito documentation by forking and cloning this repository, updating or adding content, and submitting a pull request for review.
- Required documentation tools
- File system layout of the
main-kogito
branch - Contributing to Kogito documentation
- Contributing to Kogito software
To work with the kie-docs
documentation source, you need the following software:
-
Git: Used for version control with this repository.
To install Git on Fedora, CentOS, or RHEL, enter the following command in a command terminal (in Fedora, replace
yum
withdnf
):# yum install git
For Windows, Mac OS X, and other Linux distributions, follow the instructions in the Git documentation.
-
Asciidoctor (for AsciiDoc): Used for publishing content written in AsciiDoc format, which is the format used in Kogito documentation files.
To install Asciidoctor on Fedora, CentOS, or RHEL, enter the following command (in Fedora, replace
yum
withdnf
):# yum install asciidoctor
For Windows, Mac OS X, and other Linux distributions, follow the instructions in the Asciidoctor documentation.
-
Atom (text editor): Used to edit Kogito documentation files. You can use another text editor of your choice or your existing integrated development environment (IDE), but Atom is recommended for optimal support of AsciiDoc and Asciidoctor and has many helpful add-on packages.
To install Atom on Fedora, CentOS, or RHEL, go to the Atom homepage, download the appropriate RPM version, navigate to the downloaded file in a command terminal, and enter the following command (in Fedora, replace
yum
withdnf
):# yum install -y atom.x86_64.rpm
For Windows, Mac OS X, and other Linux distributions, follow the instructions in the Atom documentation.
-
Apache Maven 3.5.4 or later: Used for building the KIE community version of Kogito documentation. To install Maven on Fedora, CentOS, or RHEL, enter the following command in a command terminal (in Fedora, replace
yum
withdnf
):# yum install maven
For Windows, Mac OS X, and other Linux distributions, follow the instructions in the Maven documentation.
The files in the main-kogito
branch of the kie-docs
repository are organized in the following general structure:
├── _artifacts
├── _images
├── doc-content
├── kogito-docs
└── src
└── main
└── asciidoc
├── bpmn
├──chap-kogito-developing-process-services.adoc
├── ...
├── configuration
├── chap-kogito-configuring.adoc
├── ...
├── ...
└── index.adoc
└── pom.xml
├── ...
├── pom.xml
└── README.md
The file structure contains the following core folders:
-
_artifacts
: Directory with document attributes that render according to target output (community or enterprise). -
_images
: Directory with all images used in the documentation, divided into sub-directories by subject matter. -
doc-content
: Directory with all ADOC content files, specifically indoc-content/kogito-docs/src/main/asciidoc
. This directory contains the following types of ADOC files:- Chapter files: Chapter files (prefix
chap-
) formatted to accommodate a modular documentation structure that is generated separately from this source repository for Red Hat enterprise documentation. For more information about modular documentation conventions, see the Red Hatmodular-docs
repository in GitHub. If any formatting conventions are unclear to you, use existing content as a starting template and write what makes sense to you. Thekie-docs
documentation team can work with the content that you contribute. - Index file: Single index file (
index.adoc
) that lists chapter files withinclude
statements and contains any additional introductory content for the Kogito documentation as a whole.
- Chapter files: Chapter files (prefix
After you install the required documentation tools, you can begin contributing to Kogito documentation in the main-kogito
branch of the kie-docs
repository. The kie-docs
documentation workflow follows the standard GitHub flow, which requires your own GitHub fork of the upstream source repository and a local clone of your fork.
The following is a high-level view of the content workflow between the upstream kie-docs
GitHub repo, your GitHub fork of the repo, and your locally cloned copy of your fork:
Prerequisites
- You have installed the required documentation tools.
- You have a basic understanding of GitHub workflows and commands.
- You have a basic understanding of AsciiDoc and Asciidoctor formatting and functionality.
Procedure
-
Fork the
kie-docs
repository in GitHub, and in a command terminal, clone your forked repository to a local directory and add a remote for theupstream
repository.Cloning your fork:
$ cd PATH_TO_REPO_DIRECTORY $ git clone git@github.com:USER_NAME/kie-docs.git
Adding and verifying the upstream remote:
$ git remote add upstream https://github.com/apache/incubator-kie-docs.git $ git remote -v origin git@github.com:jsmith/kie-docs.git (fetch) origin git@github.com:jsmith/kie-docs.git (push) upstream https://github.com/apache/incubator-kie-docs.git (fetch) upstream https://github.com/apache/incubator-kie-docs.git (push)
-
Check out the
main-kogito
branch from your upstream remote and create a working branch based on that branch to begin making changes. You can name your branch based on a JIRA ID, such asKOGITO-1234
orBXMSDOC-1234
, or another logical name if the branch is not JIRA-based, such asUpdate-DMN-content
.Creating your work branch:
$ git checkout --track upstream/main-kogito $ git checkout -b Branch-name
-
Open your Atom text editor (recommended) or other editor of your choice, and update or add content as needed according to the file system layout requirements.
-
After you complete and save your changes in your working branch, navigate to the top-level
kie-docs
directory in your local repository and enter the following commands to build the documentation locally and verify the generated preview in a web browser.Building and verifying the documentation:
$ cd ~/kie-docs $ mvn clean install -Dfull [Build output] $ google-chrome doc-content/kogito-docs/target/generated-docs/html_single/index.html
Replace
google-chrome
with the browser of your choice. -
After you build and verify your changes, commit and push your branch to your fork in GitHub.
Committing and pushing to your fork:
$ cd ~/kie-docs #Recommended to move back "up" in the directory to ensure all modified files are staged and committed. $ git add --all $ git commit -m "KOGITO-1234: Update section on DMN data types." $ git push -u origin KOGITO-1234 #For first-time push, subsequently just `git push`
-
In your
kie-docs
fork in GitHub, create a pull request to merge your work branch with themain-kogito
branch in the upstreamkie-docs
repository.In your pull request, include the following components:
- Description: Summarize your changes and include any links to JIRA tasks or document previews, if available
- Reviewers: Assign two reviewers from the Apache KIE community. If you do not know who to assign ask on Zulip channels.
To contribute to Kogito software, see the incubator-kie-kogito-runtimes
repository in GitHub.