HOWTO: Spin a new release#

Set up a build environment#

Using Anaconda, create a build environment and install the current source:

conda env create --name cf_build --file package/environment-build.yml
conda activate cf_build
pip install --editable .

Tests#

  • We use two continuous integration platforms to run tests and build binaries and documentations: GitHub Actions, ReadTheDocs.

    Finished releases are published to GitHub releases, Anaconda Cloud, and the Python Package Index.

  • Make sure that the cytoflow tests pass, both locally and on GitHub:

    nose2 -c package/nose2.cfg cytoflow.tests

  • Run the same tests but saving figures, and scroll through to make sure nothing is too strange:

    nose2 -c package/nose2.cfg --saveFigures figs.pdf cytoflow.tests

  • Make sure the cytoflowgui tests pass. You must do this locally; I’m still working on why it doesn’t run on the CI platform.

    nose2 -c package/nose2.cfg cytoflowgui.tests

  • Make sure the GitHub Actions are running to completion at cytoflow/cytoflow

Documentation#

Test the packaging#

  • Build the conda package locally:

    conda build package/conda_recipes/cytoflow

  • Install the local package in a new environment:

    conda create --name cytoflow.test --use-local cytoflow

  • Activate the test environment, make sure you can import cytoflow, and make sure the GUI runs:

    conda activate cytoflow.test
python -c "import cytoflow"
cytoflow

  • Make sure that the pyinstaller distribution will build and run on your local machine (back in your development environment).

    pyinstaller package/pyinstaller.spec
dist/cytoflow/cytoflow

  • Make sure that pyinstaller built the executables on all three supported platforms. On each of the three supported platforms:

    • Download the one-click from GitHub Actions. Make sure it starts and can execute a basic workflow.

    • Download the conda package from GitHub Actions. Create a local anaconda environment and install it. Check that it runs as both a module and a GUI

      # edit environment.yml for your platform
conda env create --name cf.test -f environment.yml
conda activate cf.test
conda install ./cytoflow-*******.conda
python -c "import cytoflow"
cytoflow

Versioning and dependencies#

  • We’re using setuptools-scm to manage versions. No manual versions required.

  • If there are dependencies that don’t have packages on Anaconda, add recipes to package/conda_recipes (using conda skeleton) and upload them to the Anaconda Cloud. Unless there’s a really (really!) good reason, please make them no-arch.

  • Make sure install_requires in pyproject.toml matches environment.yml

Note

You don’t have to set version numbers!

  • Update the version integers in package/installer.nsis

Tag the release#

  • Create a new tag on the master branch. This will re-build everything on the CI builders.

  • Download the artifacts.

Sign the Windows installer#

To get rid of the “Unknown developer” warning in Windows, we sign the installer. This requires a hardware crypto token, so it must be done locally.

  • Setup: If not done already, download and install the Windows Platform SDK. I’m using 8.1 because I couldn’t get 10 to install.

  • Download the Windows installer from Github.

  • Open a terminal in C:Program FilesMicrosoft Platform SDKBin.

  • Start the signing wizard:

    signtool.exe signwizard

  • Select the installer binary.

  • Under “Signing options”, choose “Typical”

  • Under “Signature Certificate”, choose “Select from store…”. If the hardware key is installed and set up properly, Windows should find the correct certificate.

  • Add a description such as “Flow cytometry software”. For “Web location”, specify “http://cytoflow.readthedocs.org”

  • Check the box next to “Add a timestamp to data”. Enter “http://time.certum.pl”. (Probably could use digicert or some other service.)

  • When prompted, enter the Common Profile PIN.

  • After the wizard closes, double-check that the signing process was completed by right-clicking on the executable and checking the “Digital Signatures” tab.

Sign the Mac applications#

Recent versions of MacOS will simply refuse to run an unsigned application. Some day we may have this in the CI, but at the moment it must be done locally – and the build has to happen on the same machine that the signing does. Ugh.

Update the homepage#