= Release Procedure

== Projects and Artifacts
Following sections describe what projects are part of the OptaPlanner release procedure and their resulting
release artifacts.

=== OptaPlanner

* JAR files hosted on Maven Central
* https://download.jboss.org/optaplanner/release/latestFinal[Distribution Zip]
available via a link on the optaplanner-website
* https://docs.optaplanner.org/latestFinal/optaplanner-docs/html_single/index.html[Documentation]
available via a link on the optaplanner-website
* XML Schema Definition files for both the https://www.optaplanner.org/xsd/solver/[Solver]
and the https://www.optaplanner.org/xsd/benchmark/[Benchmark] available on the optaplanner-website

=== OptaPlanner Quickstarts

No build artifacts are required; as a result of the release, the `development` branch must be rebased onto
the `stable` branch and must point to the released final version of OptaPlanner.

=== OptaWeb Employee Rostering and Vehicle Routing

* https://www.optaplanner.org/download/download.html[Distribution Zip] available via a link on the optaplanner-website
* https://www.optaplanner.org/learn/documentation.html[Documentation] available via a link on the optaplanner-website

=== OptaPlanner Website
The website contains https://github.com/kiegroup/optaplanner-website/blob/main/_config/pom.yml[links]
to the Distribution Zip files and documentation (see above). To update the documentation, and the Distribution Zip,
upload them to the `filemgmt.jboss.org` and then, open a PR changing the links.

For the OptaPlanner project, there is a https://github.com/kiegroup/optaplanner/blob/main/build/release/upload_distribution.sh[script]
uploading the documentation and the Distribution Zip. The release pipeline calls the script and updates also
the links on the website. For the Optawebs, the upload has to be done manually at this moment.

== Versioning

=== Project Version

The project uses https://semver.org/[semantic versioning] with a `.Final` suffix  for stable releases.
After a feature release MAJOR.MINOR.0.Final, the version on the `main` branch upgrades to MAJOR.MINOR+1.0-SNAPSHOT.
The next feature release is MAJOR.MINOR+1.0.Final.

As an example, the first version released by this procedure is going to be 8.0.0.Final. After the release,
the `main` branch upgrades to 8.1.0-SNAPSHOT. The next release is 8.1.0.Final.

=== Release Branches

Release branches are created for every feature release and named based on the released version by using the following convention:
Version MAJOR.MINOR.0.Final releases from a branch MAJOR.MINOR.x. After the release, this branch upgrades to MAJOR.MINOR.1-SNAPSHOT.

For example, the version 8.0.0.Final is released from a release branch 8.0.x, which is then upgraded to 8.0.1-SNAPSHOT version of the OptaPlanner.

At that moment, the branch is prepared for a patch release, if needed.

== Release Steps

This chapter describes steps required to release artifacts enlisted above, as well as other preliminary and
postliminary actions.

=== 1. Release the version in Jira

Navigate to the https://issues.redhat.com/projects/PLANNER?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page[Releases page in JIRA],
find the version to be released and pick “Release” from the Actions.

=== 2. Run `kogito-release-pipeline`

OptaPlanner is released as a part of the Kogito release pipeline. Thus, a person releasing Kogito triggers the pipeline.
Make sure you agree with this person on setting the correct OptaPlanner version before running the pipeline.

=== 3. Upgrade versions to the next snapshot
*_This step is yet to be automated._*

After the pipeline finishes, upgrade the version on the `main` branch of OptaPlanner to the next minor snapshot version,
e.g. 8.0.0.Final -> 8.1.0-SNAPSHOT. Upgrade also the version of Kogito by editing
the value of the property `version.org.kie.kogito` in the `optaplanner-build-parent`.

=== 4. Release OptaPlanner Quickstarts
*_This step is yet to be automated._*

. Create a release branch from the `development` branch.
. Upgrade the OptaPlanner version in the `parent` section of the `pom.xml` and via the `version.org.optaplanner`
property in all quickstarts, including Gradle build files, to the release version.
. https://issues.redhat.com/browse/PLANNER-2230[Sync-up the stable branch from the release branch.]
. Open a PR to the `stable` branch.
. Create and push a tag for the release.
. Upgrade the version to the next patch snapshot version on the release branch.
.. Make sure the project builds.
. Push the release branch.
. Upgrade the version of the project to the next minor snapshot version via a PR to the `development` branch.

== Kogito Release Pipeline

The `kogito-release-pipeline` is a Jenkins pipeline that covers releases of the Kogito and the OptaPlanner projects
together. As both projects consist of several Github repositories, the top-level `kogito-release-pipeline` orchestrates
multiple pipelines that operate on the project, or the repository level.

Please refer to the https://github.com/kiegroup/kogito-pipelines/blob/main/docs/nightly_and_release.md[Kogito release pipeline documentation]
for more details.

=== Actions covered by the Kogito release pipeline
* Create releases branches and upgrade the projects to the release version.
* Build the projects and deploy maven artefacts into a staging repository on JBoss Nexus.
* Promote maven artifacts from the staging repository to a public one and later release this repository to Maven Central.
* Upload the documentation and the distribution of all projects to the `filemgmt.jboss.org`.
* Update links in the optaplanner-website to point to the released artifacts.
* Upgrade version to the next bugfix snapshot on the release branch.
