Creating a release

Standard Release

Project is ready to be released not for a specific event, e.g. at the end of a sprint. Script Generator version number always differs to the client’s.

Pre Testing

  1. Find out anything that needs to be in the release that isn’t and mark with for release label. (This does not prevent a release)

  2. Ensure the version of cs-studio referenced in the GUI’s target platform is recent enough to include the most recent changes in the isis_css_top repository.

  3. Update the upgrade script to include the latest version (this is done on master). Steps to do this are in Config Upgrader in section creating a production upgrade script

    1. After committing these changes to master on the EPICS-upgrade submodule, don’t forget to push the new submodule version to master on the top EPICS branch. This is needed to make sure you changes appear on the release branch created in the next step.

  4. For packages which are published on PyPI, in particular genie_python and ibex_bluesky_core, create PyPI releases if needed.

    1. These packages are released by performing a git tag x.y.z on a checkout of main, where x.y.z is the new version you want to release. Push the tag using git push origin tag x.y.z. They will then build in github actions, and prompt to “approve” the release pipeline to PyPI.

    2. genie should be released with a version number matching the main IBEX version number. The release takes around 15 minutes in GHA.

    3. ibex_bluesky_core should generally have a minor/patch version incremented for now until we reach v1. The release takes a couple of minutes in GHA.

    4. Ensure these releases were successful by checking on pypi for the new release number before proceeding.

  5. Start the Github Actions pipeline create-release-branches.

    • Click on ‘Run workflow’

    • Set VERSION to the new release version (e.g. X.x.m).

    • Set TAG if you wish to branch off a commit other than the latest top level HEAD. If you do branch off an earlier commit, also set REMOTE to false as it now does not make sense to verify if you are on the latest submodule versions.

    • The script will then (as selected):

      • Create the release branches (named Release_X.x.m except Release_Script_Gen_X.x.m for script generator) for:

        • EPICS and submodules.

        • IBEX GUI.

        • Script Generator.

        • Uktena.

      • Update or add version numbers:

        • In ioc/master/INSTETC/INSTETC-IOC-01App/Db/svn-revision.db.tmpl for EPICS.

        • In /uk.ac.stfc.isis.ibex.e4.client/pom.xml and /uk.ac.stfc.isis.ibex.e4.client/META-INF/MANIFEST.mf for IBEX GUI.

        • In /uk.ac.stfc.isis.scriptgenerator.client/pom.xml and /uk.ac.stfc.isis.scriptgenerator.client/META-INF/MANIFEST.mf for Script Generator.

        • Note: genie_python library version numbers are set automatically from the git tag, and no longer need manually updating.

      • Push these changes to remote release branch.

  6. Start all of these builds in Jenkins.

  7. Copy the new version’s release notes (copy & paste) into a new blank Release Notes "X.x.m" (where X.x.m is the upcoming version) file and clear the contents: Check that all of the merged tickets have also had their release notes merged. Check that the release notes are as understandable as possible.

  8. Create a released version entry in the releases table (including link to release notes) and commit to master.

  9. Update the “Latest Stable Release” and “Upcoming release” links on the IBEX wiki homepage to be the new release and commit to master.

  10. If applicable, update the dependencies since the last release and add them to the bottom of the release notes. To find the python dependencies list, run a pip freeze on a cleanly released uktena. Note that you will need to specify the scripts directory to run pip commands. i.e. C:\Instrument\Apps\Python3\Scripts\Pip.exe freeze

  11. copy the release to the git$ share on control-svcs (see Keeper for the username and password for this), this is so we can set git remotes for hotfixes etc. as part of the deploy. So if release is number 1.2.3

    • robocopy "\\isis\inst$\Kits$\CompGroup\ICP\Releases\1.2.3\EPICS\.git" "\\control-svcs.nd.rl.ac.uk\git$\releases\1.2.3\EPICS.git" /mir /nfl /ndl

    • edit EPICS.git\config on the control-svcs version (you can browse straight to the \\control-svcs share above)

      • change bare = false to bare = true

      • Add an extra section at end of file

[http]
        receivepack = true

  1. Do the same for the EPICS32 32-bit build, replacing EPICS with EPICS32 everywhere in the commands above.

  2. Check release is now listed in https://control-svcs.isis.cclrc.ac.uk/git/?a=project_list;pf=releases

Testing

Update \\isis\shares\ISIS_Experiment_Controls_Public\ibex_utils - this is so the most recent install script will be used for testing and install. You should:

  • do a git branch and check it is on master and not e.g. a test or ticket branch

  • do a git status and check for any changes, if there are post on Teams

  • do a git pull so you are on the latest master branch with no local changes

One or more people should do manual system tests, using this page.

Post Testing

These steps should only be done once all changes to a release have been made and we are ready to deploy. Here we are creating a tag which will become inconsistent if further changes are made to the release branch. Hence it is important to delete the relevant release branch after it has been tagged.

  1. Create a release tag in the EPICS, ibex_gui and uktena repositories. For each repo

    1. Go to [REPO_URL]/releases, e.g. https://github.com/ISISComputingGroup/ibex_gui/releases

    2. Click Draft a new release

    3. Enter the tag version in the format vX.x.p and target the release branch

    4. Enter the title Release version X.x.p

    5. Add a link to the release notes in the description

    6. Delete the release branch once the release and tag has been created.

  2. Create release tag from the release branch for each submodules in EPICS, then delete the release branch. To do this, run the following two git commands in top level EPICS (replace X.x.x with the release number):

    1. git submodule foreach --recursive "git fetch && git tag Release_ibex_X.x.x origin/Release_X.x.x || exit 0" // Create tag

    2. git submodule foreach --recursive "git push origin tag Release_ibex_X.x.x && git push --delete origin Release_X.x.x || exit 0" // Push tags and delete release branch

    Note: you may need to run git config fsck.badEmail ignore for the above step

  3. Make sure any changes on the release branch are merged back onto master for EPICS, ibex_gui, and uktena (except version numbering)

  4. Consider which instruments need this release:

    • Breaking release: upgrade everyone

    • Big improvement: upgrade everyone if there is a big improvement that everyone will benefit from

    • Standard release: upgrade instruments that need updates, i.e. they need a newly released feature, and all those that are in the current release group, see column in instruments table. Note on the release ticket which instruments need to be released to using checkboxes (one for start and one for finish).

  5. Create repository for recording instrument changes post release the deploy script automatically puts the instrument onto a branch of this repository

Partial Release

For any release in which GUI version increments but server version does not, ensure the previous server version is added to the release folder via symbolic links or junctions, see this ticket.

Patch Release

The is a release when a change needs to be made between standard releases; i.e. a standard release is inappropriate because it includes lots of code which has not been through a code freeze and test.

  1. Follow all Pre Testing steps above except:

    • For step 4 (creating the release branch) instead of creating from master create it from the latest release tag

    • Update GUI Java JRE

    • Finding the most significant change

    • Updating the MySQL and Java being deployed

  2. Is the code for the bug/enhancement already written?

    • No: Make the changes on the branch.

    • Yes: Cherry pick commits needed from the branch with the written code

  3. Test

  4. Release as per a standard release but

    1. Use this branch instead of master

    2. Only include the change you have made in the release notes

    3. Copy the release notes issues into the development page

  5. Merge the new code back into master

Adding late commits to the release Branch for EPICS

  1. Test and merge the change into master

  2. Create a release branch in the submodule (if it doesn’t exist)

    1. Navigate to EPICS in github

    2. navigate to the submodule

    3. Create new branch (this means it will be branched from the release point)

  3. Switch the branch of the submodule: git checkout Release_X.x.m

  4. Pull the latest release branch: git pull

  5. Merge in the ticket git merge XXX

  6. push that branch

  7. cd to EPICS

  8. checkout release branch and pull

  9. update submodule reference, commit and push.