Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[incubator-kie-drools#5758] Update drools-docs for v10 #5770

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -453,7 +453,7 @@ The `KieResources` provides many convenient factory methods to convert an ``Inpu
.KieResources
image::KIE/BuildDeployUtilizeAndRun/KieResources.png[align="center"]

NOTE: `URLResource` is no longer available with Drools 8 series, to ensure a more reproducible knowledge base build (avoiding remote URLs) and for better security. If you used `URLResource` in the past, you can manage the local-fetch of the remote resource externally to your Drools application, so to limit Drools build concerns to local resources containing knowledge assets.
NOTE: `URLResource` is no longer available since Drools 8, to ensure a more reproducible knowledge base build (avoiding remote URLs) and for better security. If you used `URLResource` in the past, you can manage the local-fetch of the remote resource externally to your Drools application, so to limit Drools build concerns to local resources containing knowledge assets.

Normally the type of a `Resource` can be inferred from the extension of the name used to add it to the ``KieFileSystem``.
However it also possible to not follow the Kie conventions about file extensions and explicitly assign a specific `ResourceType` to a `Resource` as shown below:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

= Rule Unit API

Previous sections in this chapter explained traditional KIE APIs to use {RULE_ENGINE}. However, as introduced in xref:getting-started/index.adoc#first-rule-project_getting-started[First Rule Project], Rule Unit is a new and recommended style for implementing rules in {PRODUCT} 8.
Previous sections in this chapter explained traditional KIE APIs to use {RULE_ENGINE}. However, as introduced in xref:getting-started/index.adoc#first-rule-project_getting-started[First Rule Project], Rule Unit is a new and recommended style for implementing rules since {PRODUCT} 8.

A rule unit is an atomic module defining a set of rules and a set of strongly typed *data sources* through which the facts processed by the rules are inserted. The *data sources* of 2 kinds: `DataStream` and `DataStore` which will be described later in this section.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

= Rule Unit DSL

In addition to the standard Rule Unit API, {PRODUCT} 8 offers an alternative way of writing rules in combination with Rule Unit.
In addition to the standard Rule Unit API, {PRODUCT} offers an alternative way of writing rules in combination with Rule Unit.
You can now define the rules for Rule Units using a dedicated set of Java APIs.

TIP: As an end-user, you can think of the Rule Unit DSL as an alternative to DRL, in order to define your rules with an internal DSL using Java.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,22 +1,9 @@
// Do NOT delete repeated or superfluous variables unless the same can be deleted from all other attributes docs (for DM, PAM, jBPM, etc.). All attributes here are in use in product docs at this time, and as we single source, we need those same variables to render appropriately for Drools. But do please correct and add info where necessary. (Stetson, 2 Aug 2018)

:PRODUCT: Drools
:PRODUCT_SHORT: Drools
:PRODUCT_INIT: drools
:PRODUCT_INIT_CAP: DROOLS
:PRODUCT_INIT_BA: drools
:PRODUCT_INIT_CAP_BA: DROOLS
:PRODUCT_DROOLS: Drools

:PRODUCT_OLD: Drools
:URL_COMPONENT_PRODUCT_OLD: drools

:PRODUCT_VERSION: {COMMUNITY_VERSION}
:PRODUCT_VERSION_LONG: {COMMUNITY_VERSION_LONG}
:PRODUCT_FILE: {PRODUCT_INIT}-{COMMUNITY_VERSION_LONG}
:PRODUCT_FILE_BA: {PRODUCT_INIT_BA}-{COMMUNITY_VERSION_LONG}

:URL_COMPONENT_PRODUCT: drools

:RULE_ENGINE: Drools rule engine

Expand Down
Original file line number Diff line number Diff line change
@@ -1,17 +1,7 @@

:REBUILT: Tuesday, April 05, 2022


:ENTERPRISE_VERSION: 7.12
:ENTERPRISE_VERSION_LONG: 7.12.0
:COMMUNITY_VERSION: 7.59
:COMMUNITY_VERSION_LONG: 7.59.0
:COMMUNITY_VERSION: 10.0
:COMMUNITY_VERSION_LONG: 10.0.0
:COMMUNITY_VERSION_FINAL: {COMMUNITY_VERSION_LONG}.Final
:COMMUNITY_VERSION_BRANCH: 7.59.x
:ENTERPRISE_VERSION_SHORT: 712

// For copyright
:YEAR: 2022
:COMMUNITY_VERSION_BRANCH: 10.0.x

ifdef::DROOLS,JBPM,OP[]
:MAVEN_ARTIFACT_VERSION: {COMMUNITY_VERSION_FINAL}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This guide walks you through the process of creating a simple Drools application

== Creating a project with maven archetype

You can choose a style of rule project from Rule Unit or traditional style. Rule Unit is a new style that is recommended for microservices and cloud native applications. Traditional style is the same as Drools 7. Both styles are supported in Drools 8.
You can choose a style of rule project from Rule Unit or traditional style. Rule Unit is a new style that is recommended for microservices and cloud native applications. The traditional style has been used since Drools 7. Both styles are supported in Drools 10.

=== Rule Unit style

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Each rule must have a unique name within the rule unit. If you use the same rule

[id="new-and-traditional-syntax_{context}"]
== New and traditional syntax
In Drools 8, we promote a new DRL syntax based on rule unit, data source, and OOPath. Hence, you will see such a new syntax in DRL syntax examples. However, Drools 8 still fully supports traditional DRL syntax that has been used in version 7 and prior.
In Drools 10, we promote a new DRL syntax based on rule unit, data source, and OOPath. Hence, you will see such a new syntax in DRL syntax examples. However, Drools 10 still fully supports traditional DRL syntax that has been used in prior versions.

.Example rule for loan application with traditional syntax
[source]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
[id='kie-server_{context}']
== {KIE_SERVER}

{KIE_SERVER} is retired and no longer a component of {PRODUCT} 8. If your system is working on {KIE_SERVER} with {PRODUCT} 7, consider migration to https://kogito.kie.org/[{KOGITO}].
{KIE_SERVER} is retired and no longer a component since {PRODUCT} 8. If your system is working on {KIE_SERVER} with {PRODUCT} 7, consider migration to https://kogito.kie.org/[{KOGITO}].

While {KIE_SERVER} hosts multiple kjar containers, One {KOGITO} instance hosts one domain service. Hence, you would create {KOGITO} project per kjar container, which would be microservice style.

Expand All @@ -12,7 +12,7 @@ You can find the detailed migration steps in the next sections, xref:con-migrati
[id='business-central_{context}']
== {BUSINESS_CENTRAL}

{BUSINESS_CENTRAL} is retired and no longer a component of {PRODUCT} 8. For asset management, the usual version control system is recommended, for example, git. For editors, https://marketplace.visualstudio.com/items?itemName=kie-group.vscode-extension-kogito-bundle[VS Code Kogito extension] is recommended.
{BUSINESS_CENTRAL} is retired and no longer a component since {PRODUCT} 8. For asset management, the usual version control system is recommended, for example, git. For editors, https://marketplace.visualstudio.com/items?itemName=kie-group.vscode-extension-kogito-bundle[VS Code Kogito extension] is recommended.

[id='bpmn-integration_{context}']
== BPMN integration / Rule flow
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
[id='traditional-to-ruleunit_{context}']

= Migrate to {PRODUCT} 8
= Migrate to {PRODUCT} 10

This guide explains how to migrate {PRODUCT} 7 projects to {PRODUCT} 8 projects.
Firstly, migration from {PRODUCT} 8 to {PRODUCT} 10 is very simple. You just need to change the version in `pom.xml`. All APIs and DRL syntax are compatible.

Firstly, {PRODUCT} 8 supports {PRODUCT} 7 APIs and DRL syntax, so basically you don't need to change your Java codes and rule assets. However, there are some cautions in `pom.xml`.
This guide rather focuses on how to migrate from {PRODUCT} 7 projects to {PRODUCT} 10 projects.

{PRODUCT} 10 supports {PRODUCT} 7 APIs and DRL syntax, so basically you don't need to change your Java codes and rule assets. However, there are some cautions in `pom.xml`.

Typical {PRODUCT} 6 or early 7 projects have pom dependencies like this.

Expand Down Expand Up @@ -36,11 +38,11 @@ But since {PRODUCT} 7.45.0, `drools-engine` and `drools-engine-classic` have bee
</dependency>
----

{PRODUCT} 8 made some module refactoring, so you may find some difficulty in collecting dependencies. This aggregator dependency would help.
Some module refactoring were made during the version upgrades, so you may find some difficulty in collecting dependencies. This aggregator dependency would help.

== Rule Unit

As introduced in xref:getting-started/index.adoc#first-rule-project_getting-started[First Rule Project], using Rule Units is a recommended style for implementing rules in {PRODUCT} 8. It will require some modifications to your codebase, but if you are going to develop cloud-native applications, Rule Units are strongly recommended, because {KOGITO} also works with Rule Units.
As introduced in xref:getting-started/index.adoc#first-rule-project_getting-started[First Rule Project], using Rule Units is a recommended style for implementing rules in {PRODUCT} 10. It will require some modifications to your codebase, but if you are going to develop cloud-native applications, Rule Units are strongly recommended, because {KOGITO} also works with Rule Units.

.Rule Unit pom.xml
[xml,subs=attributes+]
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
== 10.0.0 release notes

=== PLACE_HOLDER

PLACE_HOLDER

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

54 changes: 8 additions & 46 deletions drools-docs/src/modules/ROOT/pages/release-notes/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -7,59 +7,21 @@ include::../_artifacts/document-attributes.adoc[]
[id='{context}']
= Release Notes

This chapter contains the release notes for the {PRODUCT} 8-series.
This chapter contains the release notes for the {PRODUCT} 10-series.

For the release notes of the _previous releases_, you can refer to the {PRODUCT} documentation of link:https://docs.drools.org/7.73.0.Final/drools-docs/html_single/index.html#droolsreleasenoteschapter[version 7].
For the release notes of the _previous releases_, you can refer to the {PRODUCT} documentation of link:https://docs.drools.org/8.44.0.Final/drools-docs/drools/release-notes/index.html[version 8].

include::_release-notes-8.40.adoc[leveloffset=0]
// This is a placeholder for adding the release notes per minor version
// include::_release-notes-10.0.adoc[leveloffset=0]

include::_release-notes-8.33.adoc[leveloffset=0]

include::_release-notes-8.32.adoc[leveloffset=0]

include::_release-notes-8.31.adoc[leveloffset=0]

== Drools 8-series release notes

Drools 8-series is a natural evolution of the 7.x-stream, incorporating many features and lessons learned integrating with Kogito and many cloud-native use cases.

=== Rule Unit

Rule Unit is a central paradigm in the Drools 8-series.
You can refer the xref:migration-guide/index.adoc[Migration guide chapter] for more information about Rule Unit.
== Drools 10-series release notes

=== Minimum requirements update

JDK 11 is now the minimum Java version required to compile Drools and make use of Drools.
JDK 17 is now the minimum Java version required to compile Drools and make use of Drools.

Maven `3.8.6` is now the minimum Maven version required to build Drools from source, or using `kie-ci` APIs.
Maven `3.8.6` is the minimum Maven version required to build Drools from source, or using `kie-ci` APIs.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the minimal Maven version is now 3.9.3. Is that correct @jstastny-cz please?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

drools itself is 3.8.6 https://github.com/apache/incubator-kie-drools/blob/main/build-parent/pom.xml#L89

But actually, our GHA runs with 3.9.3 to meet Quarkus 3.2 LTS <proposed-maven-version>3.9.3</proposed-maven-version>.

I'm good with changing the doc to 3.9.3 as a requirement.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for clarification. Then I think the doc is fine. If we will find that the Maven version would be good to update, it can be done in a separate PR.


=== `drools-mvel` and `drools-engine-classic` are deprecated

`drools-mvel` is now deprecated in favor of the executable model. It also means `drools-engine` is recommended instead of deprecated `drools-engine-classic` that contains `drools-mvel`. You can still use MVEL syntax in your rules, so it doesn't affect how to write rules.

=== Spreadsheet decision tables file extensions

All the files with `.xls`, `.xlsx` and `.csv` extensions were considered and parsed as decision tables. In general, this was a too strong assumption, breaking projects containing random excel files that are not decision tables and generating artificial compile-time errors. To prevent such problems the filename extension policy has been changed, considering and processing files as decision tables only if their extension is prepended with `.drl`. In other words, **only** files with `.drl.xls`, `.drl.xlsx`, and `.drl.csv` extensions will now be compiled as decision tables. For example: `rules.drl.xls` is a valid extension and will be included for rule compilation when found in a KJAR based project.

=== Security Manager deprecation

The {PRODUCT} features related to the JDK Security Manager will not be further developed, as starting with JDK17, the Java Platform has deprecated the Security Manager for removal.
You can refer the xref:KIE/index.adoc#_securitymanager[Security Manager chapter] for more information.

=== KIE Marshallers notice

The `KieMarshallers` are still present and working as expected on the release of the Drools 8-series, however we are currently exploring alternative solutions more idiomatic to cloud-native use cases.

=== {KIE_SERVER} is retired
{KIE_SERVER} is no longer a component of {PRODUCT} 8. For migration, see xref:migration-guide/index.adoc#kie-server_migration-guide[Migration guide chapter].

=== {BUSINESS_CENTRAL} is retired
{BUSINESS_CENTRAL} is no longer a component of {PRODUCT} 8. For migration, see xref:migration-guide/index.adoc#business-central_migration-guide[Migration guide chapter].

=== OSGi support is retired
{PRODUCT} 8 no longer provides out of the box OSGi support in its modules.

== Previous release notes

For the release notes of the previous releases, you can refer the {PRODUCT} documentation of link:https://docs.drools.org/7.73.0.Final/drools-docs/html_single/index.html#droolsreleasenoteschapter[version 7].
`drools-mvel` is deprecated since Drools 8 in favor of the executable model. It also means drools-engine` is recommended instead of deprecated `drools-engine-classic` that contains `drools-mvel`. You can still use MVEL syntax in your rules, so it doesn't affect how to write rules.
Loading