Skip to content

DevNotes_Processeses_DeploymentProcess

Jump to bottom Edit New page
Paul Butler edited this page Feb 6, 2023 · 23 revisions

Release Process

(last updated 2/6/2023 by PDB)

The following outlines the SasView release process.

Reminders

Planning a new major release

  • Releases are discussed at the bi-weekly meeting.
  • Once the content and version of the release are agreed upon, a release branch will be created.
  • Once the release branch is created, all changes destined for this release should be made against that branch (except in the case of a "cherry-pick only" release discussed later), while all other commits should continue against sasview main or sasmodels master. NOTE: don't forget to close the relevant tickets upon merging either with the closes #ticketno key phrase in the merge notes or manually.
  • Once all approved changes have been merged into master (or is clearly imminent), the release should be discussed at the following conference call and a release manager appointed.
  • The release manager will be responsible for following the release process below and communicating progress to the team. The release manager will need to have release privileges on the repository and ideally Mac and Windows signing authority, though that can be delegated to the current key holder(s) as needed.
  • Once the release is final (after all alphas and betas etc), the release branch becomes frozen and should be merged back into main and master
  • In some cases it may become necessary to create a release branch from a past tag. In this case it may be useful to use a "cherry-pick only" model where all commits continue to be made against master or main and only those relevant to the planned release get cherry-picked into that release. In this case merging back into main/master is not appropriate.

Testing a new major release

Besides the ongoing testing with every pull request, extra care in testing should be taken for a major release. This is typically done by producing a pre-release "release candidate" (tagged as beta 1 or b1). Once a signed pre-release is available on the github release page, notification should be sent out to users willing to test. This should at a minimum include the user mailing list and twitter. Other lists or individuals identified should also be informed. The developer group should also make an effort to thoroughly exercise the product.

All bugs and issues identified during this testing phase will be ticketed and either fixed or discussed on the conference call to ascertain if they must be fixed (blockers) or can remain known issues to be reported in release notes and fixed in a future release.

Depending on the number and severity of issues found, further release candidates may be produced for further testing based on discussions at the fortnightly meetings and the leadership team. Once the final release is made, the release manager will ensure that the final clean up steps are taken such as moving the "latest release" pointer on github.io to the newest version etc.

Release steps performed by the release manager or delegate

Many of the steps have been automated and get done by running the automation script. You should probably take a look at the script to makes sure it is still doing what these instructions assume.

  • Create the release_x.y.z branch in both sasview and sasmodels (NOTE: the version number will be different for sasview and sasmodels but the release.yml will need to be updated to build from the correct release numbers)
  • Lock both branches to force PR for all commits to the release branches
  • In sasview edit the installers/installer.iss file with the new version number for the installer target folder
  • Edit the release github action (/sasview/.github/workflows/release.yml) to ensure the release build is against all the appropriate version of packages including bumps and sasmodels.
    • NOTE: In the future all workflows may get contained in one ci.yml making use instead of requirements.txt which will hold all the dependencies. Please change these instructions as appropriate)
  • Edit the /sasview/build_tools/release_automation.py to ensure the list of developers/contributors is complete and up to date.
  • Run the automation script (/sasview/build_tools/release_automation.py) by following the instructions this should accomplish the following previously manual steps

update sasview (Part of automation script - should not have to do manually)

  • Obtain the Zenodo DOI
    • edit build_tools/generate_zenodo_record.py
      • add zenodo_api_key
      • modify 'title', 'description', 'related_identifiers'
      • check if developers/contributor list is up-to-date
    • execute script
    • copy DOI from the script output
  • Update src/sas/sasview/_init_.py with
    • The Zenodo link
    • The new version number
    • The year of the release (used in various copyright notices)
  • Update the current year string in:
    • LICENSE.TXT
    • /installers/license.txt

update sasmodels (Part of automation script - should not have to do manually)

  • Update sasmodels.__init__.py to the correct version number
  • Update the copyright date in LICENSE.txt

The rest (below) still needs to be done manually

  • In sasview update date in _copyright string variable in src/sas/qtgui/Utilities/LocalConfig.py
  • In sasview update docs/sphinx-docs/source/conf.py
    • Update "release=x.x.x" variable
    • Update "copyright = u'20XX, The SasView Project' variable
  • In sasview update the /sasview/docs/sphinx-docs/source/user/RELEASE.rst with the latest version of the release notes. Notice that these include changes in sasmodels as well as obvious user facing changes originating from upgrading to newer versions of 3rd party pacakges.
  • In sasmodels update CHANGES.rst with sasmodels release notes

Penultimate steps (after the last build)

  • On github create the release page using the pre-release option. MAKE SURE IT IS LABELED Pre-release! This will prevent it from being found as a latest release. Alpha and beta releases should remain tagged as "pre-release" so they don't ever get tagged as latest. Only a final release should get the latest tag. This process can be started early by making a draft release.
    • NOTE: creating a Draft release will NOT create a tag (so more changes can still be made to the branch before it actually gets tagged.
  • Current convention is to
    • Tag using the label vX.Y.Zrcj (rcj is only for pre-releases of coure)
    • Title SasView X.Y.Zrcj
  • Edit the release page text following previous release page structure. In particular copy and paste the current release notes from /sasview/docs/sphinx-docs/source/user/RELEASE.rst (not those from previous releases) and then edit them for the different markup language.
  • When ready the installers built after the last changes to the repos should be downloaded and signed/notarized for MacOS and Windows as appropriate (IMPORTANT: make sure sasview has the last change pushed so that it picks up the last changes in sasmodels. The installer action is based in the sasview repo)
  • Upload the signed installers to the release page. Current naming conventions are:
    • Windows: setupSasView-V.v.v-x64.exe
    • mac: SasView-V.v.v-MacOSX.dmg

Pre-release (alpha, beta, rc etc) final steps

  • The release manager will email the team to announce the release process is complete.
  • The team should download the new release to make sure it installs and opens.
  • For pre-releases do NOT remove the pre-release tag -- just announce on restricted "friendly user" channels and ask for feedback

Full release Final and cleanup steps steps

  • Follow first two steps in the Pre-release final steps
  • Update the release number in latestversion.json on the SasView website repo which will alert all SasView users that a new version is available.
  • Update the github release page to remove the pre-release tag which will make this now the current release found by SasView web pages.
  • Add the new documentation to the github docs repo and update github.io webpages accordingly (see steps below)
  • Update the webpages with the new release announcement
  • Upload sasmodels release to pypi (see steps below)
  • Send out the announcement to the community
  • merge the release branches back into main/master

Update posted documentation

Currently we only maintain an html copy of the documentation available on the SasView website. We originally also made a PDF and hopefully will eventually get that working again. In the meantime only the HTML instructions below are relevant.

HTML version

  • The documentation folder contents (html version) needs to be moved to the docs repo.
    • NOTE: this is no longer in the sasview.github.io website repository. It is in its own separate repository called docs
  • The first step it to git create a new folder (docs_x.y.z) under docs/old_docs where x.y.z is the version number being superseded (i.e. the version of the docs currently in the repo).
  • Git move all the folders and files currently under docs to old_docs/docs_x.y.z
  • Git copy the new html docs (all folders and files) to the docs repository
    • NOTE: While the docs could be built locally, for consistency with the release docs it is strongly recommended that the release version be installed locally and the docs copied from the install path. These can just be git copied into the docs repo folder.
  • Commit and push these changes

PDF Version

  • Eventually the documentation should also built as a PDF at which time the PDF link for the website also needs to be updated to the new PDF version.
    • NOTE: the downloads folder containing the PDF is still in the sasview.github.io website repository
    • Again, the first step is to git move the SasViewDocumentation.pdf to downloads/Old_SasViewDoucmentation/
      • NOTE: It should be renamed to SasViewDocumentation_X.y.z.pdf where X.y.z is the version number for that documentation file
    • PDF should be downloaded as SasViewDocumentation.pdf.
    • The pdf should then be git copied or git moved to the sasview.github.io/downloads folder.
    • Commit and push changes

Uploading sasmodels to pypi

sasmodels are also avaialble from pypi (sascalc should be avaialable in the future). In order to do this, one needs to checkout the tagged version and then build dist in sasmodels folder: python setup.py sdist bdist_wheel Once this is done one can upload sasmodels to pypi using twine (can be pip installed): twine upload dist/*. One needs to have a login at pypi.org and be part of sasview organization there

Post release steps

Once the release is completely done and out, it is recommended that the version numbers in src/sas/sasview/_init_.py of master get updated to the next planned release version number + alpha.1 so that developers testing can easily tell they are running a post release version and of which one. Ideally merges to main would increment the alpha number but is probably not important enough to try to enforce rigorously.

Add a custom footer

HOME

The Developers' Corner

(Potential) Contributors Resources

Helping others to use SasView

Code & Contributor Camps

Clone this wiki locally