Skip to content
This repository has been archived by the owner on Apr 6, 2023. It is now read-only.

Cutting a release of examples pse

Jump to bottom
Dan Gunter edited this page Nov 13, 2021 · 4 revisions

Overview

The examples-pse needs the "normal" tag/push/release steps as well as an extra "pre-build" step needed to generate static HTML & RST versions of the jupyter notebooks for correct presentation on the ReadTheDocs site.

These steps should be done on a machine where the IDAES get-extensions is supported and a CPLEX solver is installed.

Create new release branch

  1. On github (if not already created) create a new "release" branch for this release, named after just the major and minor versions for the release. i.e. 1.5_rel for the 1.5.0, 1.5.1, etc. release series (which will all exist on this 1.5_rel branch).

  2. Clone/checkout that new branch and update the version number in ./docs/conf.py on this release branch (to version used above).

  3. Commit and push that change to the release branch up to github.

  4. Create the new release in github on the examples-pse release branch using the github releases page to create a new tag and release on the new release branch (not main). Fill in the new tag to create, the name of the release, the release notes, select the "pre-release" checkbox for release candidates then publish.

  5. Now on main, if not already done, change the same docs/conf.py to have the dev version of the next release, i.e 1.6.0dev0 and push that up to main, since that is now the dev version of the next release. Also, make sure that the new versions of IDAES and the examples are added to the idaes-compatibility.json file located in the repository's root.

  6. For final (non-release candidate) releases I will also delete any outdated release candidates on github - which will NOT remove the tags created but will remove the headings for the old releases. I do this just to make that page a little cleaner and to avoid confusion with older releases.

Documentation

We are hosting the examples-pse documentation on Github Pages. They are pre-generated and added to the gh-pages branch of examples-pse.

One-time system and solver installation

Install pandoc (one of the following):

dnf --enablerepo=PowerTools install pandoc  # CentOS 8
apt-get install pandoc # Ubuntu

Gurobi

https://www.gurobi.com/downloads/gurobi-software/

CPLEX

https://www.ibm.com/analytics/cplex-optimizer

ALAMO

  • Request a license (note: It's free for DOE, using your email addr)
  • Download for your platform
  • Unzip into location of your choice, to be used later
  • When you get the license, place it in that same dir

BARON

  • Request a license (IDAES team members could likely get a "friend" license)
  • Download for your platform
  • Unzip into location of your choice, to be used later
  • When you get the license, place it in that same dir

Build the gh-pages docs

Start with a new conda env "examples-rel" and install of the latest idaes-pse

conda create --name examples-rel python=3.7 -y
conda activate examples-rel
pip install idaes-pse

Get/test solvers in place:

idaes --version  # Just to make sure idaes is there
idaes get-extensions                 # or use --platform (use `idaes get-extensions-platforms` to list)
find $(idaes data-directory) -ls     # Look at what idaes ext bits are installed
PATH=$PATH:$(idaes bin-directory)    # get ipopt on PATH
ipopt -v                             # confirm
ldd $(which ipopt)                   # confirm
PATH=$PATH:~/opt/ibm/ILOG/CPLEX_Studio_Community129/cplex/bin/x86-64_linux   # get cplex on PATH
cplex -c help                        # confirm
PATH=$PATH:~/opt/alamo-linux64       # get alamo on PATH
alamo                                # confirm that you have a proper license
PATH=$PATH:~/opt/baron-lin64         # get baron on PATH
ldd $(which baron)                   # confirm
export GUROBI_HOME=~/opt/gurobi/gurobi911/linux64
PATH=$PATH:$GUROBI_HOME/bin
export LD_LIBRARY_PATH=$GUROBI_HOME/lib:$LD_LIBRARY_PATH
gurobi

To check if pyomo finds a given solver try (replacing ipopt with cplex, alamo, baron or gurobi):

python -c "from pyomo.environ import *; print(SolverFactory('ipopt').available())"

Set up release workspaces

Get ready to build docs using 2 examples-pse workspaces: one on the release (e.g. 1.7_rel) and one on the gh-pages branches:

git clone -b 1.7_rel git@github.com:IDAES/examples-pse.git examples-pse-rel
git clone -b gh-pages git@github.com:IDAES/examples-pse.git examples-pse-gh-pages

In the release, load requirements to build:

cd examples-pse-rel
pip install -r requirements.txt   # This might need to come from idaes-pse's setup.py's extras_require["dev"] list

Use the build.py script to put notebooks in the docs

Step 1: Wipe any old notebooks (-r) and run the notebooks (-e). This will take at least several minutes.

python build.py -re

Step 2: Copy notebooks into docs tree, build the docs, and build the notebook index page

python build.py -drx

Copy built docs into release directory

In examples-pse-gh-pages, copy HTML files from examples-pse-rel build directory into new directory named for version, e.g. "1.6.2"

cp -r ../examples-pse-rel/docs/_build/html 1.6.2

Update latest link and add new release directory to git:

ln -sf 1.6.2 latest
git add 1.6.2 latest

Commit all changes and push (directly) to the gh-pages branch

git commit -am "releasing docs for {version}"
git push

GitHub does the rest. It may take a minute or two. Verify it's installed by visiting (replace "{version}" with the version you just released)

Clone this wiki locally