Kusuma04-dev commented on code in PR #62: URL: https://github.com/apache/incubator-kie-website/pull/62#discussion_r4391293068
########## docs/community/devs/release-procedure.md: ########## @@ -0,0 +1,577 @@ +--- +id: release-procedure +title: Release Procedure +sidebar_position: 1 +--- + +This document describes how to perform an Apache KIE release. It covers the repositories involved, how branches and tags are named, and every step from creating a release candidate to publishing the final release. + +:::note +Starting with **10.3**, all Java components (Drools, OptaPlanner, Kogito Runtimes, and Kogito Apps) were merged into a single repository called `incubator-kie`. This means the release process is now a **two-repo** workflow (one command or Jenkins job per repository) instead of the multi-repo process used in 10.2. +::: + +--- + +## Overview + +A KIE release involves two repositories: + +| Repository | What it contains | Language / tooling | +|---|---|---| +| [`incubator-kie`](https://github.com/apache/incubator-kie) | Drools, OptaPlanner, jBPM, Kogito | Java / Maven | +| [`incubator-kie-tools`](https://github.com/apache/incubator-kie-tools) | VS Code extensions, Chrome extensions, web apps like KIE Sandbox, container images, Helm charts | Node.js / Go / pnpm | + +All release scripts live inside each repository: +- **`incubator-kie`**: [`script/release/`](https://github.com/apache/incubator-kie/tree/main/script/release/) — each script supports `--dry-run`. See the [`README.md`](https://github.com/apache/incubator-kie/blob/main/script/release/README.md) there for the per-script reference. +- **`incubator-kie-tools`**: [`scripts/release/`](https://github.com/apache/incubator-kie-tools/tree/main/scripts/release/) — see the [`README.md`](https://github.com/apache/incubator-kie-tools/blob/main/scripts/release/README.md) there for details. + +This page is the **single source of truth** for the release procedure. The `RELEASING.md` files in both repositories only point here. + +### Who can run a release + +A release is run by an Apache KIE **Release Manager (RM)**, a PPMC member or a committer designated by the PPMC. Running the Jenkins jobs requires: + +- Permission to trigger jobs in the Apache KIE Jenkins instance. +- Write access to `apache/incubator-kie` and `apache/incubator-kie-tools` (to push stream branches and tags). +- Your GPG key in the [Apache KIE KEYS file](https://downloads.apache.org/incubator/kie/KEYS) when you sign locally. +- An ASF account with access to `repository.apache.org` (Nexus) and `dist.apache.org` (SVN) to close/release the staging repository and move artifacts. + +### Credentials used by the Jenkins jobs + +These are configured in Jenkins, not typed in by the RM. Running locally needs the equivalent values in your environment. + +| Credential | Used by | Local equivalent | +|---|---|---| +| Maven `settings.xml` with the `apache.releases.https` server (Config File Provider, default id `kie-release-authn-settings`) | `incubator-kie` release job | `MAVEN_SETTINGS=/path/to/settings.xml` | +| GPG signing key (secret file, default id `GPG_KEY_FILE`) and optional passphrase | `incubator-kie` release job; `incubator-kie-tools` release-candidate job | Your local GPG agent, or `MAVEN_GPG_PASSPHRASE` | +| GitHub push credential (username/password) | Pushing stream branches and tags in both repositories | SSH key or token with push access | +| ASF SVN staging credential (id `kie-svn-credentials`) | `incubator-kie-tools` release-candidate job (upload to `dist/dev`) | `svn` with your ASF account | +| npm token, VS Code Marketplace PAT, Chrome Web Store tokens, Docker Hub and Helm registry credentials, GitHub token | `incubator-kie-tools` release-publish job | `NPM_TOKEN`, `VSCE_PAT`, `CHROME_*`, `DOCKER_*`, `HELM_*`, `GITHUB_TOKEN` | + +### Where the output goes + +| Output | Location | +|---|---| +| Java artifacts (JARs, POMs, sources, Javadocs) | Nexus staging repository `orgapachekie-XXXX` at [repository.apache.org](https://repository.apache.org) | +| Tools RC artifacts, signatures and checksums | `https://dist.apache.org/repos/dist/dev/incubator/kie/<rc-version>/` | +| Release tags | `X.Y.Z-rcN` and `X.Y.Z` in each repository | +| Tools public artifacts | npm, VS Code Marketplace, Chrome Web Store, Docker Hub, GitHub Release | + +### Jenkins jobs + +| Repository | Jenkinsfile | Purpose | +|---|---|---| +| `incubator-kie` | `.ci/jenkins/Jenkinsfile.103xplus.release` | Stream branch cut (optional), RC tag, build, deploy to Nexus staging | +| `incubator-kie` | `.ci/jenkins/Jenkinsfile.103xplus.promote` | Final tag, GitHub Release, upload of Drools binaries and documentation | +| `incubator-kie` | `.ci/jenkins/Jenkinsfile.103xplus.deploy` | Stream snapshot version bump and deploy (not part of the release steps below) | +| `incubator-kie-tools` | `.ci/jenkins/Jenkinsfile.103xplus.release-candidate` | Stream branch cut (optional), RC tag, build, sign, upload to SVN `dist/dev` | +| `incubator-kie-tools` | `.ci/jenkins/Jenkinsfile.103xplus.release-publish` | Publish to public registries | + +:::note +The `incubator-kie` `103xplus` Jenkinsfiles are **not** registered in `.ci/jenkins/dsl/jobs.groovy`, so no job is generated for them. Create each one as a "Pipeline script from SCM" job pointing at the Jenkinsfile. The `release` Jenkinsfile needs only its parameters. `promote` and `deploy` still read environment variables that the DSL normally injects (`REPO_NAME`, `GIT_AUTHOR`, `PROPERTIES_FILE_NAME`, `JENKINS_EMAIL_CREDS_ID`, `GIT_AUTHOR_PUSH_CREDS_ID`, ...), so set them on the job. +::: + +--- + +## 1. Repositories & Requirements + +### `incubator-kie` (Java) + +| Item | Value | +|---|---| +| Stream branch | `10.3.x` | +| RC tag | `10.3.0-rc1` | +| Final tag | `10.3.0` | +| OS | Linux or macOS | +| JDK | Temurin 17.0.12+ (21 also works) | +| Maven | 3.9.6+ | +| Docker | 25+ | +| Build command | `./script/release/release-all.sh --version 10.3.0 --tag 10.3.0-rc1 --skip-tests` | +| Deploy command | add `--deploy --push-tag` to the build command | +| Produced artifacts | JARs, POMs, sources, and Javadocs deployed to Apache Nexus Staging | +| Update version | `./script/release/01-update-version.sh <version>` *(automated by `release-all.sh`)* | + +### `incubator-kie-tools` (Node.js / Go) + +| Item | Value | +|---|---| +| Stream branch | `10.3.x` | +| RC tag | `10.3.0-rc1` | +| Final tag | `10.3.0` | +| OS | Linux or macOS | +| Node.js | 24 or newer (`engines.node` is `>=24`) | +| pnpm | 10.34.4 (pinned by `packageManager`; enabled through `corepack`) | +| Go | 1.26 (`go 1.26.0` in the Go modules) | +| Bash | 4 or newer. `release-all.sh` uses associative arrays; the Bash 3.2 shipped with macOS does not work, install it with `brew install bash` | +| Helm | 3.x | +| Docker | 25+, **running**. If Docker is not running, container images are skipped | +| Build command | `./scripts/release/release-all.sh 10.3.0 --rc` | +| Publish command | `./scripts/release/release-all.sh 10.3.0 --publish` | +| Update own version | `pnpm update-version-to <version>` and `pnpm update-stream-name-to <stream>` | +| Update Java version | `pnpm update-kogito-version-to --maven <version>` | +| Produced artifacts | VS Code extensions (`.vsix`), Chrome extensions, web app ZIPs, NPM packages ZIP, Sources ZIP, container image tarballs, Helm chart tarballs, upload-service binaries — all in `release-artifacts/` | + +:::warning +`release-all.sh` does not fail when Docker is not running; it prints a warning and **skips the container images**. Before you sign and upload an RC, check that the container image tarballs are present in `release-artifacts/`. +::: + +--- + +## 2. Branches & Tags + +### How branches and tags are named + +| Name format | Example | Purpose | +|---|---|---| +| `main` | `main` | Ongoing development | +| `X.Y.x` | `10.3.x` | Stream branch for a minor release series | +| `X.Y.Z-rcN` | `10.3.0-rc1` | Release candidate tag | +| `X.Y.Z` | `10.3.0` | Final release tag | + +### Version numbers on branches + +- **`main`** always runs `999-SNAPSHOT` (Java) or `0.0.0` (Tools) — a placeholder version that is never released. +- **Stream branch (`10.3.x`)** runs `10.3.999-SNAPSHOT` (Java) or `10.3.999` (Tools) — again a placeholder, never released. +- **RC and final tags** point to a temporary commit where the version is set to the exact release version (e.g. `10.3.0`). That temporary commit is created locally and immediately deleted after tagging — only the tag is pushed. + +### Git timeline diagram + +``` +main: ---c-------c---c---c----------------------------------> main + v999-SNAPSHOT + | + '----D---c---c---c---c-------------------------> 10.3.x + | | v 10.3.999-SNAPSHOT + | | + | '--R--> tag 10.3.0-rc2 ✅ + | tag 10.3.0 + | + '--R--> tag 10.3.0-rc1 ❌ (vote failed) +``` + +**Diagram key:** + +| Symbol | Meaning | +|---|---| +| `c` | Regular commit | +| `D` | Dev-version commit — sets version to `X.Y.999-SNAPSHOT` on the stream branch | +| `R` | Release commit — sets version to exact release version (e.g. `10.3.0`) on a temporary local branch, tagged, then discarded | +| `✅` | Vote passed | +| `❌` | Vote failed — a new RC is needed | + +--- + +## 3. Release Steps + +The recommended way to run a release is via Jenkins. Each step below describes the Jenkins approach first, followed by the equivalent local commands. + +--- + +### Step 1 — Create the Stream Branch + +> **When:** Once per minor release series, before creating the first RC. +> **Example:** Creating `10.3.x` before releasing `10.3.0`. + +This step creates the `10.3.x` branch in both repositories and sets their versions to the development placeholder (`10.3.999-SNAPSHOT`). + +#### 1a. Duplicate the `main` Jenkins folder + +Before you cut the branch, duplicate the `main` folder in Jenkins as `10.3.x` (copy the folder and its jobs, then point the jobs at the `10.3.x` branch). This lets `main` keep evolving without affecting a release that is in progress on `10.3.x`. Run all Jenkins jobs for this release from the `10.3.x` folder. + +Do this once per minor series. Patch releases (`10.3.1`, ...) reuse the same folder. + +#### 1b. Cut the branch + +##### Via Jenkins + +**There is no separate job to run in this step.** In both repositories the branch cut is done by the **first RC run in Step 2**, by setting extra parameters on it. The job creates `10.3.x` from `main`, sets the development version, pushes the branch, and then builds the RC on it, all in the same build. Do not run a branch-cut build first and an RC build afterwards: the second build would fail because the branch already exists. + +For `10.3.0-rc1`, use the "First RC of a new minor" row of the "Parameters by type of run" table in Step 2. For every later run, leave the branch-cut flags `false` and use `BASE_REF=10.3.x`. + +For `incubator-kie-tools` only, `UPDATE_CI_IMAGE_TAG` is an extra option on the branch-cut run. Set it to `true` only if the `incubator-kie-tools-ci-build:10.3.999` image has already been built and pushed; otherwise leave it `false`, or the jobs on the new branch cannot start. + +##### Locally + +**`incubator-kie`:** +```bash +chmod +x script/release/*.sh + +# Dry run first — checks branch status without making changes +./script/release/00-create-stream-branch.sh 10.3.0 --dry-run + +# Create the branch, set version to 10.3.999-SNAPSHOT, and push +./script/release/00-create-stream-branch.sh 10.3.0 --push +``` + +**`incubator-kie-tools`:** +```bash +git checkout main && git pull +git checkout -b 10.3.x + +pnpm update-version-to 10.3.999 +pnpm update-stream-name-to 10.3.x +pnpm update-kogito-version-to --maven 10.3.999-SNAPSHOT + +git add -A +git commit -m "chore: update version to 10.3.999" +git push origin 10.3.x +``` + +--- + +### Step 2 — Build & Stage a Release Candidate + +> **When:** Each time you create a new RC (e.g. `10.3.0-rc1`, `10.3.0-rc2`). + +This step builds all artifacts, signs them, and uploads them to staging for community verification. + +#### Parameter checklist (read before triggering any job) + +Most failed releases come from a wrong parameter, and several parameters have no validation in the Jenkinsfile. Check these before you click **Build**: + +| # | Check | Why | +|---|---|---| +| 1 | The version fields are filled in and consistent: `TAG_NAME` / `RELEASE_CANDIDATE_VERSION` is `<RELEASE_VERSION>-rcN` | The Java job validates this; the Tools RC job does **not**. Its defaults are `0.0.0` / `0.0.0-rc1`, so an untouched run pushes a `0.0.0-rc1` tag. | +| 2 | The RC number is new: `git ls-remote --tags origin '<tag>'` returns nothing in **both** repositories | A tag that already exists makes the job fail (see [Troubleshooting](#6-troubleshooting)). | +| 3 | Java job: its SCM branch is `10.3.x` (except for the branch-cut run) | The Java job has no branch parameter. It builds whatever branch the job is configured for and only prints a warning when that is not the stream branch. | +| 4 | Tools job: `BASE_REF` is `10.3.x` (and `main` only for the branch-cut run) | `BASE_REF` defaults to `main`. Forgetting to change it for `rc2` tags `main` content as `10.3.0-rc2`. | +| 5 | Branch-cut flags (`CREATE_STREAM_BRANCH`, `UPDATE_STREAM_VERSION`) are `true` **only** for the first RC of a new minor | They fail when `10.3.x` already exists. | +| 6 | Java job: `DEPLOY=true`, `PUSH_TAG=true`, `DRY_RUN=false` for the real run | With `DEPLOY=false` nothing reaches Nexus; with `PUSH_TAG=false` the tag stays on the agent and is lost when the workspace is wiped; with `DRY_RUN=true` nothing remote happens. | +| 7 | Credential ID parameters keep their defaults unless your Jenkins uses other IDs | A wrong ID fails the job when it first needs the credential. | +| 8 | For the very first run of a release, do a Java run with `DRY_RUN=true` first | It checks the parameters and the build without touching remote state. | + +#### Parameters by type of run + +The same two jobs are used for every RC. Only the parameters differ: + +| Run | Java `Jenkinsfile.103xplus.release` | Tools `Jenkinsfile.103xplus.release-candidate` | +|---|---|---| +| **First RC of a new minor** (`10.3.0-rc1`) | `RELEASE_VERSION=10.3.0`, `TAG_NAME=10.3.0-rc1`, `CREATE_STREAM_BRANCH=true`, `STREAM_BASE_BRANCH=main`, `DEPLOY=true`, `PUSH_TAG=true` | `RELEASE_VERSION=10.3.0`, `RELEASE_CANDIDATE_VERSION=10.3.0-rc1`, `BASE_REF=main`, `CREATE_STREAM_BRANCH=true`, `UPDATE_STREAM_VERSION=true` | +| **Next RC after a failed vote** (`10.3.0-rc2`) | `TAG_NAME=10.3.0-rc2`, `CREATE_STREAM_BRANCH=false` | `RELEASE_CANDIDATE_VERSION=10.3.0-rc2`, `BASE_REF=10.3.x`, branch-cut flags `false` | +| **Patch release** (`10.3.1-rc1`) | `RELEASE_VERSION=10.3.1`, `TAG_NAME=10.3.1-rc1`, `CREATE_STREAM_BRANCH=false` | `RELEASE_VERSION=10.3.1`, `RELEASE_CANDIDATE_VERSION=10.3.1-rc1`, `BASE_REF=10.3.x`, branch-cut flags `false` | + +The parameters not listed keep their defaults. The first-RC run and every later run use the **same job**; the branch-cut flags are the only difference (see Step 1b). + +If a job fails, do not simply re-run it: the RC tag is pushed before the build, so a plain re-run fails with "tag already exists". See [Troubleshooting](#6-troubleshooting). + +#### 2a. Java reactor (`incubator-kie`) + +**Via Jenkins:** +Trigger `Jenkinsfile.103xplus.release` with the parameters for your run from the table above. + +**Locally:** +```bash +git checkout 10.3.x && git pull + +# Dry run — builds everything locally, no remote changes +./script/release/release-all.sh \ + --version 10.3.0 \ + --tag 10.3.0-rc1 \ + --skip-tests \ + 2>&1 | tee /tmp/kie-release-run.log + +# Real run — creates the RC commit, pushes the tag, and deploys to Nexus staging +MAVEN_SETTINGS=/path/to/settings.xml \ +MAVEN_GPG_PASSPHRASE=<your-gpg-passphrase> \ +./script/release/release-all.sh \ + --version 10.3.0 \ + --tag 10.3.0-rc1 \ + --skip-tests \ + --deploy \ + --push-tag \ + 2>&1 | tee /tmp/kie-release-run.log +``` + +#### 2b. Close the Nexus staging repository + +After Step 2a (Java deploy) succeeds: +1. Go to [repository.apache.org](https://repository.apache.org) → **Staging Repositories**. +2. Find your `orgapachekie-XXXX` repository. +3. Click **Close**. +4. Copy the staging repository URL — you will need it in the voting email. + +If the deploy failed part-way, **Drop** the partial staging repository instead of closing it (see [Troubleshooting](#6-troubleshooting)). + +#### 2c. KIE Tools (`incubator-kie-tools`) + +**Via Jenkins:** +Trigger `Jenkinsfile.103xplus.release-candidate` with the parameters for your run from the table above. + +Jenkins builds, signs, and uploads all artifacts to Apache SVN Dev Dist at: +`https://dist.apache.org/repos/dist/dev/incubator/kie/10.3.0-rc1/` + +**Locally:** +```bash +git checkout 10.3.x && git pull +pnpm bootstrap + +# Step 1 — Build all RC artifacts into release-artifacts/ +./scripts/release/release-all.sh 10.3.0 --rc 2>&1 | tee release-10.3.0-rc.log + +# Step 2 — Sign each artifact +cd release-artifacts +for f in *; do + gpg --armor --output "${f}.asc" --detach-sig "${f}" + sha512sum "${f}" > "${f}.sha512" +done Review Comment: It is scripted Tiago but if they want to run locally , we have mentioned those steps. For each one -- via jenkins is there and also via locally is also there. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
