tag | 6f2f356c68592298f5d7b0bde74798720596f5e9 | |
---|---|---|
tagger | Jenkins CI <noreply@redhat.com> | Thu Jul 27 02:59:23 2023 -0400 |
object | 85dffd75879bee0fe72c5116d860b0da85fc1635 |
Tagged by Jenkins.
commit | 85dffd75879bee0fe72c5116d860b0da85fc1635 | [log] [tgz] |
---|---|---|
author | Jenkins CI <noreply@redhat.com> | Thu Jul 27 02:59:22 2023 -0400 |
committer | Jenkins CI <noreply@redhat.com> | Thu Jul 27 02:59:22 2023 -0400 |
tree | f506fd3336bf1f02f666ac8f6d7b4fa3e344c1f5 | |
parent | 91d30612fabe9c110d7060f2d0536023d75141c0 [diff] |
Bumped up kogito-docs version in kie-docs
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.
This master-kogito
branch of the kie-docs
repository contains the source of the Kogito documentation for both KIE community and Red Hat Business Automation enterprise publications. The latest version of the Kogito documentation for the KIE community is published at https://docs.jboss.org/kogito/release/latest/html_single/.
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.
NOTE: The other branches in the
kie-docs
repository contain the source of the Drools, jBPM, and OptaPlanner documentation, which are the basis for Red Hat Decision Manager and Red Hat Process Automation Manager.
master-kogito
branchTo 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
with dnf
):
# 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
with dnf
):
# 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
with dnf
):
# 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
with dnf
):
# yum install maven
For Windows, Mac OS X, and other Linux distributions, follow the instructions in the Maven documentation.
main-kogito
branchThe 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 ├── titles-enterprise // For Red Hat enterprise documentation testing only ├── ... ├── 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 in doc-content/kogito-docs/src/main/asciidoc
. This directory contains the following types of ADOC files:
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 Hat modular-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. The kie-docs
documentation team can work with the content that you contribute.index.adoc
) that lists chapter files with include
statements and contains any additional introductory content for the Kogito documentation as a whole.titles-enterprise
: Directory for testing Red Hat enterprise documentation. This directory is used internally by Red Hat technical writers only.
After you install the required documentation tools, you can begin contributing to Kogito documentation in the master-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
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 the upstream
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/kiegroup/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/kiegroup/kie-docs.git (fetch) upstream https://github.com/kiegroup/kie-docs.git (push)
Check out the master-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 as KOGITO-1234
or BXMSDOC-1234
, or another logical name if the branch is not JIRA-based, such as Update-DMN-content
.
Creating your work branch:
$ git checkout --track upstream/master-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 the master-kogito
branch in the upstream kie-docs
repository.
In your pull request, include the following components:
To contribute to Kogito software, see the kogito-runtimes
repository in GitHub.