Preparing a Release Package

The team aspires to develop a fully automated and continuous release process that will support up to date packages at any point in the development cycle with minimal effort. Much of this has been set in motion through the development of a continuous integration system that is capable of generating installer packages on demand.

To make a new release and associated installer packages simply "Draft a new release" using the GitHub user interface. You will be presented with a user interface to select the branch or commit that will be tagged and used to generate the release packages. The CI robots will detect this action and begin compiling and assembling installer packages which will be automatically uploaded to GitHub and made available for download.

Asking the CI system to make a new EnergyPlus installer package is simple enough, except that the package is not fully up to date without some preparation. Most of the content (binary targets) in the EnergyPlusTeam project are maintained on a continuous basis. Most notably the version information that is propagated through the various targets of the EnergyPlusTeam project is controlled from a single location in the CMakeLists.txt project file. https://github.com/NREL/EnergyPlusTeam/blob/develop/CMakeLists.txt#L7 This version identifier is incremented manually at the end of every iteration cycle and then CMake propagates the version string into the EnergyPlus IDD file, the simulation engine, and the transition program. This works smoothly except for when it comes to the transition program which is responsible for upgrading previous version idf input files to the current version. With the transition program there are some complications, and manual steps for major releases, that are described here. https://github.com/NREL/EnergyPlusTeam/blob/develop/src/Transition/README.md

The real labor comes about when combining the core EnergyPlus targets with the supporting applications and documentation. Most of this content is stored in a separate repository, EnergyPlusBuildSupport, located here: https://github.com/NREL/EnergyPlusBuildSupport When an installer package is created from the EnergyPlusTeam project (by building the "Package" target), prepared content is downloaded from the EnergyPlusBuildSupport repository and installed into the EnergyPlus package using a custom cmake command. https://github.com/NREL/EnergyPlusTeam/blob/develop/cmake/ProjectMacros.cmake#L12 Most (all?) of the invocations of this function are in CPack.cmake in the EnergyPlusTeam project. https://github.com/NREL/EnergyPlusTeam/blob/develop/CPack.cmake#L116 The maintenance burden comes about because most of the files in EnergyPlusBuildSupport are prepared content that involve some type of compiling process or manual preparation from source materials. Here is a (partial) list of the signification items that need to be prepared for a major release. Note that currently none of the content in EnergyPlusBuildSupport is maintained between two week iterations and therefore iteration builds are not kept up to date with the current development process.

• The large pdf documents such is IO Ref, Engineering Ref, and others. These are maintained as source in Microsoft Word documents and must be compiled into pdf and checked into the support repository.

• EP-Launch (and EP-Launch Lite for Mac) This is a compiled program that is updated with major releases. It is not certain if a major version is compatible with future minor version changes. Source code lives somewhere else.

• IDF-Editor is a compiled program that is updated with major releases. It is not clear what changes need to be made for major / minor version increments.

• Other binary programs that may or may not have version sensitivities. The list is very long, but some are only installed on Windows. Let's not repeat all of them in this document. See CPack.cmake install_remote commands for a complete list.

• Enhancement list items, Addressed Issues, and Known Issues. These files are maintained manually at this time, but are good candidates for generation from GitHub or other source.

• Rules8-1-0-to-8-2-0.xls, readme.html, ObjectStatus.xls, Report Variables 8-1-0-009 to 8-2-0.csv, VariableNameListAudit.xlsx

From this list there are three broad categories that need to be better integrated into the development and packaging process. Documentation, supporting binary programs, and release information / notes. Solutions are being discussed for documentation such as markdown or TeX, combined with automatic systems for compiling the resulting pdf and html product. For the binary programs it might be possible to extract the sensitivity to version from these products. This would allow the binary programs to be separated from the version increments of the core engine, and therefore versioned and (perhaps distributed) separately, with minimal maintenance overhead. Finally for release information, such as known issues, and enhancement list, the team may explore options for generating this content from GitHub or the git repository itself. If solutions are developed for all three of these categories then the release process will have much lower overhead and better support the two week iteration cycle.