How to create a new release?

This section describes the steps necessary to create a new release of the City Energy Analyst (CEA).


Each release of the CEA needs a version number. Version numbers need to increase for PyPI. The relevant documentation for python version numbers is documented in PEP440. The CEA uses the following versioning scheme in compliance with PEP440:


Major and minor version segments in this scheme refer to the milestone (sprint) the release was developed for. The major version segment works on roughly a yearly time scale while the minor version segment tracks sprints inside the major release. Each such pair (major.minor) refers to a “milestone” in the GitHub issues milestones list.

If a release needs to be updated after publishing, an optional revision can be used, starting at 1 and incrementing.

During the sprint, the pre-release section is used to represent the current state of the master branch. At the beginning of the sprint, alpha versions are used. Examples: 2.2a0, 2.2a1, 2.2a2, etc. In this phase the issues belonging to the milestone are being added.

Once the code base settles down, beta versions can be used. Examples: 2.2b0, 2.2b1, 2.2b2, etc. In this phase, new features should not be added anymore and instead testing / bug fixing activities should dominate.

Before releasing a milestone, the release candidates can be used. Examples: 2.2rc0, 2.2rc1, 2.2rc2, etc. In this phase the software is just being tested with show-stopping bugs being fixed if possible.

Where to find the current version number

The current version number can be found in the module cea (actually, since cea is a package, you need to look into the file in the variable __version__. All code requiring knowledge of the current version number should read the version from here. In python modules this can be achieved by:

The NSIS installer (see section Creating the installer) uses the helper tool setup/get_version.exe to extract the version and write it to the file setup/cea_version.txt - if importing cea is not an option, you could explore this avenue too…

Responsibility for version numbers

The repository admin merging a pull request to master is responsible for updating the version number.

Update the file

For each minor release (2.2, 2.3, …) the file needs to be updated to include all the authors that worked on that release.

Creating the installer

  • first, make sure you have the Nullsoft Scriptable Installation System (NSIS) installed. See How to set up NSIS
  • if the dependencies changed, you need to re-create the Dependencies.7z file and store it as a binary on the release.
    • Be sure to update the URL to Dependencies.7z in the file setup/cityenergyanalyst.nsi to the new release
    • To create the Dependencies.7z file, follow these steps:
      • create an empty folder called Dependencies
      • locate the conda environment for the CEA (as created with environment.yml and copy it to the Dependencies folder.
      • rename the environment folder to Python
      • use the 7z program to compress the Dependencies folder to Dependencies.7z
  • create the installer by right-clicking setup/cityenergyanalyst.nsi in Windows Explorer and choosing the “Compile NSIS Script” option.
  • upload the installer to the Release page.
  • update the document Installation guide for Windows to refer to the newest installer.

Testing in a virtual machine

In order to test the release, it is a good idea to run the installation guide / installer on a clean virtual machine, e.g. with VirtualBox. This test should go as far as running cea test –reference-case open just to be sure everything is still working. This test goes a bit further than the regular test in that it makes sure the installation instructions still work on a new installation. This is important because it can find missing packages in the dependency lists etc.

Building the documentation

An important part of the release process is ensuring that the documentation for readthedocs site can be built. This can be tested locally by executing the following commands in the repository folder:

cd docs
make clean
make html

For this to run you will need to first pip install sphinx. Also note that the command cea install-toolbox needs to be run at least once to set up some paths required for importing certain modules. You will also need to do conda install numba. You also need to install GraphViz to produce the graphs.

If any error messages show up, these need to be fixed before publishing the release. The readthedocs site uses these steps to produce the developer and API documentation.

The documentation will be build in the folder docs/_build/html and you can open the index.html file there to browse the documentation.

Changes to the conda environment need to be reflected in the docs/environment.yml file.

Uploading to PyPI

  • check long-description with this commandline:

    python --long-description | for /f %i in ('where') do python %i > %temp%\ld.html && start %temp%\ld.html
    • make sure the output is valid / no errors, as this will be the text of the CEA on PyPI
    • for to be installed, you will need to do a pip install sphinx
  • delete any old distributions from dist folder (you can just delete the whole dist folder if you like)

  • do python sdist bdist_wheel

    • this will recreate the dist folder with two files that look similar to these:
      • cityenergyanalyst-2.2-py2-none-any.whl
      • cityenergyanalyst-2.2.tar.gz
  • use twine to upload to PyPI

  twine upload dist/*

- you can get twine_ with ``pip install twine``
- the command above assumes you have set the ``TWINE_PASSWORD`` and ``TWINE_USERNAME`` environment variables
  if not, use the ``--username`` and ``--password`` positional arguments
- ask the repository admins for username and password