Release Process

Release Checklist

Note: At the bottom of this page of this page you'll find the markdown source of this checklist to paste it in a release issue

Preparation
- Create a prepare-release-x.y.z branch, based on the dev-v10 (or dev) branch; check out the prepare-release-x.y.z branch
- Update the README.txt and WHATSNEW.txt in the packaging/common/khiops directory
- Update the PDF documentation
- Update the technical repository khiops-win-install-assets
  - Update the versions of all assets that require an update, namely:
    - Khiops Visualization
    - Khiops Covisualization
    - Khiops PDF Docs
    - Java JRE installer
    - MS MPI installer
- Update Khiops version to x.y.z-(a|b|rc).w in the src/Learning/KWUtils/KWKhiopsVersion.h header file
- Create PR on the prepare-release-x.y.z branch and have it reviewed
- Once the PR is approved, merge it into the dev-v10 branch
- Create the x.y.z-(a|b|rc).w pre-release tag on the dev-v10 (or dev) branch (see Versioning)
  - Example: git tag 10.2.1-a.1 dev-v10
Full Test Loop
- Push the x.y.z-(a|b|rc).w pre-release tag
  - Example: git push origin tag 10.2.1-a.1
  - This will create a pre-release entry in the release section with all the the CICD generated packages
- Execute the end-to-end tests (aka. LearningTest) in all supported environments
  - If there are major issues, fix them (making issues, PRs) and go back to "Create pre-release tag..."
- Execute the manual tests for the GUI packages
Finalize the Release
- Update src/Learning/KWUtils/KWKhiopsVersion.h to the final release tag x.y.z
- Merge dev-v10 (or dev) into main (via PR)
- Create the final release tag (see also Versioning):
  - Tag the main branch (git tag x.y.z main then git push origin tag x.y.z)
- Copy and paste the release notes from packaging/common/khiops/WHATSNEW.txt to in the new github release entry
- Remove any packages that haven't been deemed to release
  - We create more packages than we release for testing purposes (viz. kni-transfer)
- Manually launch the conda.yml workflow on the x.y.z tag, while selecting khiops as release channel
- Sign the Windows binaries, recreate the Windows package (see packaging/windows/nsis/README.md), sign it and replace it in the release
- Set release as "latest"; unset its "pre-release" status
- Release enabler: khiops-python,
- Release enabler: khiops-notebook.
  - At this point the update of the website is unblocked
Final Git Manipulations
- Update the main branch
- Make the dev-v10 (or dev) branch point to main
  - Locally execute git fetch, then git switch main, git switch dev-v10 (or git switch dev) and git reset --hard main
  - In the repository's branch protecting settings remove temporarily "Require a pull request before merging"
  - Locally execute git push
  - Restore in the branch protecting settings "Require a pull request before merging"

Versioning

Khiops Core

The versioning scheme for Khiops has the following format MAJOR.MINOR.PATCH{-PRE_RELEASE.PR_INCREMENT} where

MAJOR is a number and marks a major release. It contains major and minor features, API changes (probably) and bug fixes.
MINOR is a number and marks a minor release. It contains minor features and bug fixes.
PATCH is a number and marks a patch release. It contains only bug fixes.
PRE_RELEASE is one of a, b, rc marks a pre-release status:
- a is an Alpha "release" : A stable version of the code that may be released for private testing.
- b is a Beta release : A release for public testing.
- rc is a Release Candidate : a candidate for a release. If we find no major bugs it may become a definitive release.
PR_INCREMENT: Numerical increment for a pre-release.

Any MAJOR, MINOR and PATCH release is widely available, so any enabler such as khiops-python or khiops-docker must be upgraded to complete the release.

After the final release for a major series, the subsequent versions are all alpha until the beta for the next version is declared. For example: The last version of the 10 series is 10.2.x so the development versions are 10.5.0-a.1 until the new major release alpha version are available.

Unlike the major versions, the pre-release are not intended to be accessible permanently. The github release containing the pre-release will be removed when the next (pre-)release will be released (although the git tag will remain).

Note about packages version: when a change appears in the package itself (no change in the binaries), a new minor version is released. It is for instance the case when the windows installer updates a new version of the khiops visualization tool.

Khiops Enablers

Enablers should use the Khiops version as an anchor and add a suffix to build their own versions.

khiops-python: https://github.com/KhiopsML/khiops-python/blob/dev/CONTRIBUTING.md#versioning
khiops-docker: TBD
khiops-visualization: TBD (Execption to the rule)

Git Tags

Tags for releases are only on the main branch. Tags for pre-release may go in dev and ocasionally in a feature branch. Currently, they trigger the creation of an entry in the "Releases" section of the GitHub repository. This entry contain all linux and windows packages. If some of them do not pass the end-to-end tests they should be removed from a final release.

Avoid deleting tags that are not alpha releases, as downstream packages (eg. khiops-python) may depend on them.

Manual Testing Procedure

Below you'll find the checklists describe the manual tests for the Khiops packages to execute upon release. Each step has variants specified as sub-bullets.

The result of each step should be report as

OK
Ok with warning:
- It works but there is a strange behavior or popup
  - We should think of a warning to put in the installation guide or troubleshooting section
KO
- Give the maximum context information to the developers to reproduce the problem

Windows

The checklist below should be performed on the following system combinations:

Versions:

Windows 10
Windows 11

Machine Types:

Personal/Home Machine
Orange IT's machines

Checklist

Check that the download link in https://khiops.org works correctly
- with Chrome
- with Edge
- with Firefox
Execute the installer
- by right clicking the installer and selecting "Execute as administrator"
- by double clicking the installer exe (not equivalent when done with a normal user)
  - check that it is signed by Orange and not "Unknown Publisher"/"Editeur Inconnu"
Select the installation directory
- the default C:\Program Files\khiops
- one within the user home directory (ex: C:\Users\<USERNAME>\khiops)
- another directory (ex: C:\Temp\khiops, C:\Applications\khiops)
Launch the Khiops applications
- From the start menu
- From the desktop icon
- From the shortcut of the installation directory
Check the version and year date (ex: 2024) of the tool and in the documentation
- From the application menu Help/About Khiops...
- In the text documents available in the installation directory: LICENSE.txt, README.txt, WHATSNEW.txt
- In the pdf documents available in doc sub-directory of the installation directory: guides and tutorial
Check in the application:
- That the menu "Open Dictionary File..." opens in C:\Users\Public\khiops_data\samples
- That Adult supervised analysis works fine
- That the resulting AllReports.khj work fine with the Khiops Visualization
Uninstall the application
- From the start menu
- From the "Apps & Features"/"Applications et Fonctionnalités" pane in the settings
Check that the files were removed
- The installation dir
- The C:\Users\Public\khiops_data\samples directory
  - But that any user generated files in the above Adult analysis have not been removed
Install/Reinstall
- Uninstall everything if necessary
- Install once with whatever method
- Install again
  - in the same directory
  - in another directory
- Check that:
  - a popup saying that "Khiops is already installed" appears and accept.
  - when installing another directory the old was removed.

Linux

The checklist below should be performed on the following system combinations:

OS:

Ubuntu 20.04
Ubuntu 22.04
Ubuntu 24.04
Debian 10
Debian 11
Debian 12
Rocky Linux 8
Rocky Linux 9

Checklist

Install with the proper method in each OS
Check output of khiops_env:
```
khiops_env --env
```

Use Docker images to seamlessly test on several Linux distributions. To do this execute the following manipulations on the host system (where Docker is launched from):

# Enable X clients to connect from any host (not only localhost)
xhost +

# Display graphics windows from the Docker container on the same screen address as the host computer
# Share UNIX sockets between the Xorgs of the host and Docker container
docker run -it --network=host -e DISPLAY=$DISPLAY -v  /tmp/.X11-unix:/tmp/.X11-unix:ro os_codename:os_version

# After Docker session is finished, secure access to the host's X server again
xhost -

Then install and launch the Khiops desktop application from the shell as usual.

Launch the Khiops applications
- From the start menu
- From the desktop icon (?)
- From a shell session (in Docker containers), via the khiops and khiops_coclustering commands
Check in the application:
- That the menu "Open Dictionary File..." opens in /usr/bin (or in the current directory where the khiops / khiops_coclustering command was launched)
- That Adult supervised analysis works fine in khiops
- That the resulting AllReports.khj work fine with the Khiops Visualization, launched on the host machine if tests are done in Docker containers
- That khiops -v, khiops -s work, when launched from a shell
- That, when launched without arguments, or with any argument except for -b, -s or -v, in a shell in a Docker without display enabled, khiops and khiops_coclustering output GUI is not available, please use the '-b' flag is generated; if a non-existing argument is passed alongside with -b, then the command's help is displayed.
Uninstall the application
Check that the files were removed
- MODL* khiops and khiops_env khiops-coclustering from /usr/bin
- norm.jar, khiops.jar from /usr/share/khiops, along with this directory as well

Release Checklist Code

- **Preparation**
  - [ ] Create a `prepare-release-x.y.z` branch, based on the `dev-v10` (or `dev`) branch;
    check out the `prepare-release-x.y.z` branch
  - [ ] Update the `README.txt` and `WHATSNEW.txt` in the `packaging/common/khiops` directory
  - [ ] Update the [PDF documentation][pdf-docs]
  - [ ] Update the technical repository [khiops-win-install-assets][win-install-assets]
    - Update the versions of all assets that require an update, namely:
      - Khiops Visualization
      - Khiops Covisualization
      - Khiops PDF Docs
      - Java JRE installer
      - MS MPI installer
  - [ ] Update Khiops version to `x.y.z-(a|b|rc).w` in the `src/Learning/KWUtils/KWKhiopsVersion.h` header
    file
  - [ ] Create PR on the `prepare-release-x.y.z` branch and have it reviewed
  - [ ] Once the PR is approved, merge it into the `dev-v10` branch
  - [ ] Create the `x.y.z-(a|b|rc).w` pre-release tag on the `dev-v10` (or `dev`) branch
    (see [Versioning][versioning])
    - Example: `git tag 10.2.1-a.1 dev-v10`
- **Full Test Loop**
  - [ ] Push the `x.y.z-(a|b|rc).w` pre-release tag
    - Example: `git push origin tag 10.2.1-a.1`
    - This will create a pre-release entry in the [release section][khiops-releases] with all the
    the CICD generated packages
  - [ ] Execute the end-to-end tests (aka. `LearningTest`) in all supported environments
    - If there are major issues, fix them (making issues, PRs) and go back to "Create pre-release tag..."
  - [ ] Execute the [manual tests for the GUI packages][manual-tests]

- **Finalize the Release**
  - [ ] Update `src/Learning/KWUtils/KWKhiopsVersion.h` to the final release tag x.y.z
  - [ ] Merge `dev-v10` (or `dev`) into `main` (via PR)
  - [ ] Create the final release tag (see also [Versioning][versioning]):
      - Tag the `main` branch (`git tag x.y.z main` then `git push origin tag x.y.z`)
  - [ ] Copy and paste the release notes from `packaging/common/khiops/WHATSNEW.txt` to in the new
        [github release entry][khiops-releases]
  - [ ] Remove any packages that haven't been deemed to release
    - We create more packages than we release for testing purposes (viz. `kni-transfer`)
  - [ ] Manually launch the `conda.yml` workflow on the `x.y.z` tag, while selecting `khiops`
    as release channel
  - [ ] Sign the Windows binaries, recreate the Windows package (see `packaging/windows/nsis/README.md`),
    sign it and replace it in the release
  - [ ] Set release as "latest"; unset its "pre-release" status
  - [ ] Release enabler: `khiops-python`,
  - [ ] Release enabler: `khiops-notebook`.
    - **At this point the update of the website is unblocked**

- **Final Git Manipulations**
  - Update the `main` branch
  - [ ] Make the `dev-v10` (or `dev`) branch point to `main`
    - Locally execute `git fetch`, then `git switch main`, `git switch dev-v10` (or `git switch dev`) and
    `git reset --hard main`
    - In the repository's [branch protecting settings][branch-settings] remove temporarily "Require a pull
    request before merging"
    - Locally execute `git push`
    - Restore in the  [branch protecting settings][branch-settings] "Require a pull request before
    merging"

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Release Process

Release Checklist

Versioning

Khiops Core

Khiops Enablers

Git Tags

Manual Testing Procedure

Windows

Checklist

Linux

Checklist

Release Checklist Code

Contents

Clone this wiki locally