Skip to content

DevNotes_Processeses_DeploymentProcess

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

Release Process

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 automation script (work in progress)

Some of the below mentioned steps can be now done with script. Take a look on it before start editing any files

Penultimate release steps performed by the release manager

sasview update

  • Create a proposed_release_x_y_z branch
  • Update the /sasview/docs/sphinx-docs/source/user/RELEASE.rst with the latest version of the release notes
  • 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 docs/sphinx-docs/source/conf.py
    • Update "release=x.x.x" variable
    • Update "copyright = u'20XX, The SasView Project' variable
  • Update date in _copyright string variable in src/sas/qtgui/Utilities/LocalConfig.py
  • Currently we also need to manually update the current year string in two places:
    • LICENSE.TXT
    • /installers/license.txt
  • When branch changes (mainly release notes) are approved merge the proposed release branch into master - then delete the branch.
  • Tag HEAD or the appropriate SasView commit point for the release. This can be done either by:
    • Use git to tag HEAD or a commit $ git tag -a vx.y.z -m "SasView version x.y.z" or
    • create a pre-release from github following instructions published on GitHub ​https://help.github.com/articles/creating-releases/ . NOTE: creating a Draft release will NOT create a tag
    • For release candidates create tags with "rcX" appendix (e.g. v5.0.2rc1)
      • NOTE 1: It is impotant at this point to label as pre-release so that the link from the webpage continues to send people to the old version as there is no executable yet for them to download from here.
      • NOTE 2: if decision is made to make a release from an old enough commit point that it is not available on the GitHub interface the tag can be generated using the local git interface

NOTE: sasview.latestversion has now been superseded by the json file stored at the sasview site.

sasmodels update

We should only be using tagged version of sasmodels in a SasView release unless there is a compelling reason to release from the current sasmodels HEAD. Assuming this release is against a NEW version of sasmodels

  • Make sure to update sasmodels.__init__.py to the correct version number
  • Manually update the copyright date in LICENSE.txt
  • Manually update CHANGES.rst
  • Tag HEAD, or the appropriate commit with the release number. To do so one can either:

Create the Jenkins release builds

  • Log into the Jenkins server, navigate to the releases tab and for each platform use "configure" to edit the configuration to use the appropriate sasmodels and SasView tags for the build.
  • Next, manually launch the Jenkins build processes for each platform being supported.

Final update of the github release page

  • Once the build process is complete, download the mac and windows builds from the Jenkins release build tab and upload the binaries to the releases page. Note that the mac and windows builds will need to be renamed appropriately. Current naming convention is:
    • Windows: setupSasView-V.v.v-x64.exe
    • mac: SasView-V.v.v-MacOSX.dmg
  • The portion of the release notes in the RELEASE.rst for this new release version should be entered in the Release Description section (i.e do not copy the full release notes which includes notes for ALL previous versions as well). Also a copy of the Acknowledgment and citation and Bug Reporting sections should be included at the end of the Release Description section… with the correct DOI and version numbers of course.

Final release 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. Because the release build servers are different than the developer build servers, build server fixes and dependency updates may not have been propagated over to the release server so some rudimentary testing should be done to double check that all is well.
  • Once final approval is given
    • Update the github release page to remove the pre-release tag which will make this now the current release found by SasView web pages.
    • The release number should be updated in latestversion.json on the SasView website repo which will alert all SasView users that a new version is available.
    • Finally update the website links to the documentation to point to the new versions - see next steps

update posted documentation

Currently we maintain both an html and a PDF copy of the documentation available on the SasView website. Make sure to follow BOTH steps below.

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

  • The documentation is also built as a PDF and 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
    • The new PDF is available on the Jenkins Master Build tab of the OSX and Ubuntu builds only. NOTE: they are not currently available in any of the release builds which means they should be downloaded from Master build immediately after last commits before tagging a release. This should be changed to add a PDF build on the release servers at some point.
    • 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 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 mergers to main would increment the alpha number but is probably not important enough to try to enforce rigourously.

Patch releases

Currently patch releases follow the same process as major releases but the cycle is usually much abbreviated.

Pre releases (alpha and beta releases)

Pre-releases follow a much less formal acceptance process but otherwise follows the same technical process - make sure to click "This is a pre-release" check box when drafting a new release on GitHub.

Add a custom footer

HOME

The Developers' Corner

(Potential) Contributors Resources

Helping others to use SasView

Code & Contributor Camps

Clone this wiki locally