Skip to content

Release Process

Jump to bottom
popescu-v edited this page Nov 8, 2024 · 51 revisions

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

    • Update the README.txt and WHATSNEW.txt in the packaging/common/khiops directory
    • Update the PDF documentation
    • Update the technical repo 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

  • Full Test Loop

    • Create a pre-release tag in the dev or *-hotfix branch. The tag may be alpha, beta or release candidate, see Versioning.
      • This will create a pre-release entry in the release section with all the the CICD generated packages
    • Create a pre-release tag in the dev or *-hotfix branch of the khiops-python repository
      • The will upload to a test channel the conda packages for Khiops
      • Example: git tag 10.2.1-a.1 dev, then git push origin tag 10.2.1-a.1
    • 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 a pre-release tag..."
    • Execute the manual tests for the GUI packages

  • Finalize the Release

    • For a MAJOR or MINOR release: Merge dev into main (via PR)
      • PATCH releases are kept and tagged *-hotfix branch
    • Create the final release tag (see also Versioning):
      • For a MAJOR or MINOR release: Tag the main branch (ex. git tag 10.3.0 then git push origin tag 10.3.0)
      • For a PATCH release: Tag the corresponding *-hotfix (ex. git tag 10.2.1 then git push origin tag 10.2.1)
    • 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 package than we release for testing purposes
    • Sign the Windows binaries, recreate the Windows package and replace it in the release
    • Release enablers: khiops-python, khiops-notebook.
      • At this point the update of the website is unblocked

  • Final Git Manipulations

    • Only for MAJOR or MINOR releases, update the main
    • Create branch *-hotfix branched from the tagged commit in main
    • Make the dev branch point to main
      • Locally execute git fetch, then git switch main, git switch dev and git reset --hard main
      • In the repo'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.

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
  • 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**
  - [ ] Update the `README.txt` and `WHATSNEW.txt` in the `packaging/common/khiops` directory
  - [ ] Update the [PDF documentation][pdf-docs]
  - [ ] Update the technical repo [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
- **Full Test Loop**
  - [ ] Create a pre-release tag in the `dev` or `*-hotfix` branch. The tag may be alpha, beta or
  release candidate, see [Versioning][versioning].
    - This will create a pre-release entry in the [release section][khiops-releases] with all the
    the CICD generated packages
  - [ ] Create a pre-release tag in the `dev` or `*-hotfix` branch of the `khiops-python` repository
    - The will upload to a test channel the conda packages for Khiops
    - Example: `git tag 10.2.1-a.1 dev`, then `git push origin tag 10.2.1-a.1`
  - [ ] 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 a pre-release tag..."
  - [ ] Execute the [manual tests for the GUI packages][manual-tests]

- **Finalize the Release**
  - [ ] For a `MAJOR` or `MINOR` release: Merge `dev` into `main` (via PR)
      - `PATCH` releases are kept and tagged `*-hotfix` branch
  - [ ] Create the final release tag (see also [Versioning][versioning]):
      - For a `MAJOR` or `MINOR` release: Tag the `main` branch (ex. `git tag 10.3.0` then `git push origin tag 10.3.0`)
      - For a `PATCH` release: Tag the corresponding `*-hotfix` (ex. `git tag 10.2.1` then `git push origin tag 10.2.1`)
  - [ ] 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 package than we release for testing purposes
  - [ ] Sign the Windows package and replace it in the release
  - [ ] Release enablers: `khiops-python`, `khiops-notebook`.
    - **At this point the update of the website is unblocked**

- **Final Git Manipulations**
  - Only for `MAJOR` or `MINOR` releases, update the main
  - [ ] Create branch `*-hotfix` branched from the tagged commit in `main`
  - [ ] Make the `dev` branch point to `main`
    - Locally execute `git fetch`, then `git switch main`, `git switch dev` and `git reset --hard
    main`
    - In the repo'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"

Contents

Clone this wiki locally