Public Software Release Process Step-By-Step Instructions¶

Software Table of Contents¶

ISIS
ALE
Plio
Knoten
USGSCSM

ISIS Public Release Process¶

ISIS release process chjanges depending on the type of release:

RC (Release Candidate)
- new feature releases are released first as RCs
  (e.g. going from 8.0->8.1 or 8.5->9.0)
LR (Live Release)
- If no changes are suggested for the RC after a month,
  do a LR from the RC.
LTS (Long Term Support)
- The previous major release is supported for a year in LTS.
- It only receives bug fixes, no feature adds.

1. Check current test failures¶

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

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

2. Update Version in AWS S3 (for ISIS Application Docs)¶

LR/LTS only, not for RCs.

Add the new version to versions.json in AWS S3
arn:aws:s3:::asc-public-docs/isis-site/versions.json

Move on to step 3 after updating versions.json.

3. Update the GitHub documents¶

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

4. Create/setup git branch¶

Clone the repo locally with git clone.

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¶

No Release for RCs

Skip this step for Release Candidates (RCs). Only pull a release if it's a full release (i.e. LR/LTS, NOT an RC). RCs should instead be in their own branch until ready for full release.

LRLTS

In the release tab on GitHub, draft a release and set the target branch to the branch created in Step 4.
On the same page, create a new tag for the release version.
Name the release "ISISX.Y.Z Public Release".

In the release tab on GitHub, draft a release and set the target branch to the branch created in Step 4.
On the same page, create a new tag for the release version.
Name the release "ISISX.Y.Z LTS".

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

Move on to step 6 after creating the release.

6. Publish Record to DOI¶

LR/LTS 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 7 after getting a DOI number and posting it to the release and readme.

Include the DOI number in the announcement in step 7 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

ALE Public Release Process¶

Step-by-step instructions for the release process of ALE.

Step 1. Update the Changelog¶

Update the Changelog to label all the currently unreleased changes as part of the new release.

Step 2. Add new entry to code.json¶

Update code.json by adding a new entry with the new version number and the date last modified.

Step 3. Update setup.py Version¶

Update version number in setup.py.

Step 4. Update CMakeLists.txt¶

Update the VERSION variable in CMakeLists.txt to the new version number.

Step 5. Update recipe/meta.yaml¶

Update the version variable in recipe/meta.yaml to the new version number.

Step 6. Submit a Pull Request¶

Submit a pull request with the changes from steps 1-5.

Step 7. Create a Github Release¶

Once your pull request as been approved and merged, draft a new github release. Tag the release with the new version. Name the release with the version number and include the changelog information in the description.

Plio Public Release Process¶

Step-by-step instructions for the release process of Plio.

Step 1. Update the Changelog¶

Update the Changelog to label all the currently unreleased changes as part of the new release.

Step 2. Add new entry to code.json¶

Update code.json by adding a new entry with the new version number and the date last modified.

Step 3. Update setup.py Version¶

Update the VERSION variable in setup.py to the new version number.

Step 4. Submit a Pull Request¶

Submit a pull request with the changes from steps 1-3.

Step 5. Create a Github Release¶

Once your pull request as been approved and merged, draft a new github release. Tag the release with the new version. Name the release with the version number and include the changelog information in the description.

Knoten Public Release Process¶

Step-by-step instructions for the release process of Knoten.

Step 1. Update the Changelog¶

Update the Changelog to label all the currently unreleased changes as part of the new release.

Step 2. Add new entry to code.json¶

Update code.json by adding a new entry with the new version number and the date last modified.

Step 3. Update setup.py Version¶

Update the VERSION variable in setup.py to the new version number.

Step 4. Submit a Pull Request¶

Submit a pull request with the changes from steps 1-3.

Step 5. Make Github Release¶

Once your pull request as been approved and merged, draft a new github release. Tag the release with the new version. Name the release with the version number and include the changelog information in the description.

USGSCSM Public Release Process¶

Step-by-step instructions for the release process of USGSCSM.

Step 1. Update the Changelog¶

Update the Changelog to label all the currently unreleased changes as part of the new release.

Step 2. Add new entry to code.json¶

Update code.json by adding a new entry with the new version number and the date last modified.

Step 3. Update CMakeLists.txt¶

Update the VERSION variable in CMakeLists.txt to the new version number.

Step 4. Submit a Pull Request¶

Submit a pull request with the changes from steps 1-3.

Step 5. Make Github Release¶

Once your pull request as been approved and merged, draft a new github release. Tag the release with the new version. Name the release with the version number and include the changelog information in the description.