ISIS Public Release Process¶

For releasing other Astro software, see the general release process

The ISIS release process changes depending on the type of release. Release Candidates (RCs) and Live Releases are only done for Major Releases (i.e, 8.x.x → 9.0.0).

RC (Release Candidate)
- Major releases are released first as RCs
  (e.g. going from 8.3.0 → 9.0.0)
LR (Live Release)
- If no changes are suggested for the RC after a month,
  do a LR from the RC.

Subsequent Production and LTS releases (with no Major version change, i.e, 8.2.0 → 8.3.0, 9.0.1 → 9.0.2), have a more streamlined release process, with no RC/LR.

LTS (Long Term Support)
- The previous major release is supported for a year in LTS.
- Only receives bug fixes, no feature adds.
Prod (Production)
- Quarterly release with (non-breaking) features and bugfixes.

1. Prepare Feeder Branch/Merge Any Unmerged Changes¶

CI/CD: Cherry-Picking

gitub-cherrypick.yml attempts to auto-cherrypick bugfixes to the next LTS branch, and bugfixes + non-breaking features to the next Prod branch, as the changes are merged into the Dev branch. Identifies bugfixes and/or non-breaking features by the checkboxes from the PR template. Not all changes are automatically resolveable, so make sure to manually cherry-pick any remaining changes that need to be included in LTS or Prod.

Triggered by pushes (including merged-PRs) to dev.

When a major update is made, make sure the script in github-cherrypick.yml can still find the latest LTS and Production branches (to cherry-pick to) correctly.

Move on to step 2 after any functional changes have been merged.

2. Check current test failures¶

Check the AWS CodeBuild test results for the branch you plan to release. If false positives are suspected, at least two contributing developers need to agree before moving forward.

CI/CD: Codebuild

gitlab-codebuild.yml auto-builds ISIS to check for build and/or test failures. The auto-build runs in a linux system, so this is a good chance to check for errors that may not occur in a local mac build.

Triggered by the creation of a PR to any branch. Makes a push to the internal isis-codebuild-ci repo, and lets that repo's CI/CD do the rest of the work (i.e. talking to AWS codebuild).

Move on to step 3 after confirming that builds are passing (or accounting for false positives).

3. Update the GitHub documents¶

If needed, install towncrier with conda install towncrier

Move on to step 4 after merging PR(s) to the feeder branch.

4. Create/Setup Release Branch¶

Clone the repo locally with git clone.

RCLRLTSProd

Working from your local branch for the RC (i.e, 8.0.0_RC1)...
Update VERSION variable in CMakeLists.txt, do not add _RC here.
Update RELEASE_STAGE variable in CMakeLists.txt to `beta``
Update recipe/meta.yaml to match the name of the RC branch. i.e. with the _RC#.
Update the build section by copying the current contents of environment.yaml into the build section.
Update the run section to include any new packages and remove any packages that are no longer needed.
Push the changes to the upstream branch (upstream/8.0.0_RC1)

Working from your local branch for the RC (i.e, 8.0.0_RC1)...
Check VERSION variable in CMakeLists.txt matches release version.
Update RELEASE_STAGE variable in CMakeLists.txt to stable.
Update recipe/meta.yml to match the LR version. i.e. without the _RC#.
Update the run section to include any new packages and remove any packages that are no longer needed. Rare for LRs, often no changes are needed.
Push the changes to the upstream branch

Create the LTS and Prod feeder branches for this major version of isis and push them to the upstream repo.

git checkout -b 8-lts upstream/8.0.0_RC1
git push -u upstream 8-lts

git checkout -b 8-prod upstream/8.0.0_RC1
git push -u upstream 8-prod

Checkout a branch from the LTS feeder branch.
- Example: git checkout -b 9-lts upstream/9-lts.
Update VERSION variable in CMakeLists.txt.
Check RELEASE_STAGE variable in CMakeLists.txt is set to stable.
Update the run section to include any new packages and remove any packages that are no longer needed.
Push to the upstream feeder branch (`upstream/9-lts')

Checkout a branch from the Prod feeder branch.
- Example: git checkout -b 9-prod upstream/9-prod.
Update VERSION variable in CMakeLists.txt.
Check RELEASE_STAGE variable in CMakeLists.txt is set to stable.
Update the run section to include any new packages and remove any packages that are no longer needed.
Push to the upstream feeder branch (upstream/9-prod)

Ensure to update the version and build_number is set to 0 in recipe/meta.yml

The build number should be incremented for each build produced at the same version of source code and should always begin at 0 for each release version. Uploading the a new build using the same build number AND version number will overwrite the previous release.

meta.yml vs environment.yml versions

Make sure you look closely at the changes in terms of syntax. Our environment.yamls seem to have a looser restriction than what is expected in the meta.yaml. Check out conda's package match specifications for more info.

Move on to step 5 after creating the new branch on the upstream repo.

5. Create a release¶

CI/CD: Conda Release

github-release.yml builds ISIS (with kakadu) and uploads those builds to conda. It also updates the ISIS Docs for the release version.

Triggered by GitHub Releases, pushes to *.*.*_RC* or *.*.*_LTS branches, or manually.

If this action fails, make sure to complete the conda build/upload manually, and keep the docs up to date.
Make sure the images this action relies on are up to date. Only the most recent two mac versions are supported, and an out of date mac image will cause this action to fail.

dev-weekly-release.yml makes a dev build of ISIS each week and uploads it to conda.

Tag custom builds as pre-release, including mission-specific and non-standard builds.

Move on to step 7 after creating the release.

6. Publish Record to DOI¶

LR/LTS/Prod only, not for RCs.

Check that the code.usgs.gov link for the release is live and create a DOI record.

Creating a DOI

A DOI is only needed for standard releases. Release candidates do not need a DOI.
Go to the USGS Asset Identifier Service (AIS) and click Manage DOIs to Login.
- You will need the assistance of USGS staff for this.
- The AIS has known compatibility issues with Firefox, if you have trouble logging in, switch browsers.
Click Create DOI and Reserve a DOI.
- Title: Integrated Software for Imagers and Spectrometers (ISIS) X.Y.Z
- Data Source: Astrogeology Science Center
- ISIS Does Not use the ScienceBase Data Release Process.
- Clicking Reserve My DOI returns the DOI that's on hold.
  - Record this number in the GitHub release, and in the ISIS Readme at the top as a badge and in the Citing ISIS section.
Add More Information
- Under "Manage Record"
  - Add other USGS Staff members who can manage the DOI.
- Under "Required Information"
  - Creator(s) / Author(s): Add the ISIS Team Lead
  - Landing Page URL: https://code.usgs.gov/astrogeology/isis/-/tags/[X.Y.Z]
  - Resource Type: Software
  - IPDS Number: IP-141314 for ISIS 8.x.x releases. Major Versions will need a new number/release approval from IPDS.
  - This product is not associated with a primary USGS-authored publication.
- Under "Recommended Information"
  - Fill info if available.
- Saving and Publishing
  - Once the Landing Page URL on code.usgs.gov is live, publish the record to DataCite.
  - You can save the record without publishing it if the release landing page is not ready.

Markdown format for DOI Number

DOI [`12.3456/XXXXXXXX`](https://doi.org/12.3456/XXXXXXXX)

Post the DOI number/link to...
- GitHub Release Post for this ISIS Version
- ISIS Readme
  - Badge at the top of the readme
  - Citing ISIS section:
    - DOI, Version Number, Release Date, Readme Updated Date

Move on to step 8 after getting a DOI number and posting it to the release and readme.

Include the DOI number in the announcement in step 8 below!

7. Announce the Build¶

Create a new ISIS3 GitHub Discussion in the announcements category.
- Fill in the Release Notes Template for the post:

Release Notes Template

ISIS X.Y.Z has been released.

DOI [`12.3456/XXXXXXXX`](https://doi.org/12.3456/XXXXXXXX)


## How to install or update to <X.Y.Z> 

A guide to [installing ISIS](https://astrogeology.usgs.gov/docs/how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda/) can be found in the Astro Software Docs.

If you already have a version of ISIS 4.0.0 or later installed in an anaconda environment, you can update to <X.Y.Z> by activating your existing isis conda environment and running `conda update isis`. 


### How to get access to <X.Y.Z> at the ASC 

Internal builds available via Hovenweep.

Once a version of conda is active, run the command: `conda activate isis<X.Y.Z>` to use this newest version of ISIS. 


## Changes for <X.Y.Z> 

<!---
Copy this release's section of the Changelog here
-->


## Notes 

Latest Operating System Support for this Release: 

* Ubuntu 24.04 
* macOS 13

(Other Linux/macOS variants and versions may be able to run this release, but are not officially supported.) 

If you find a problem with this release, please create an issue on our [GitHub issues page](https://github.com/DOI-USGS/ISIS3/issues/new/choose/)

Additional Notes for Release Candidates

Add the following under "Notes":

There are some important considerations to keep in mind when using this release candidate: 

* Do not use this version for production work. A stable isisX.XX.XX release will be uploaded after a month. 
* The ISIS online documentation will not be updated until the stable release is announced.

ISIS Release Complete