Skip to content

release‐0‐11‐0

Jump to bottom
Ludovico Bianchi edited this page Dec 15, 2023 · 1 revision

WaterTAP: cutting release 0.11.0

Create and/or update 0.11_rel release branch

  • 1: Clone repository in a fresh directory

    pushd "$(mktemp -d)"
git clone [email protected]:watertap-org/watertap.git && cd watertap

  • 2: Switch to release branch if it exists, else create it

    git checkout "0.11_rel" || git checkout -b "0.11_rel"

  • 3: Review differences with the default branch

  • 4: Cherry-pick commits onto the release branch

    # -x: append "Cherry-picked from..." to commit message
git cherry-pick -x deadbeef

  • 5: Update version and dependencies in ./setup.py (WaterTAP, DISPATCHES)

    • Open ./setup.py
    • Search for version= (in the kwargs for the call to setup()) and set version="0.11.0"
    • Search for SPECIAL_DEPENDENCIES_FOR_RELEASE and set it to SPECIAL_DEPENDENCIES_FOR_RELEASE = ["idaes-pse"]
    • Search for SPECIAL_DEPENDENCIES_FOR_PRERELEASE and set it to SPECIAL_DEPENDENCIES_FOR_PRERELEASE = SPECIAL_DEPENDENCIES_FOR_RELEASE
    • Search for install_requires=
    • Make sure only SPECIAL_DEPENDENCIES_FOR_RELEASE (i.e. the FOR_RELEASE variant) is included in install_requires
    • Save and exit
    • Open ./docs/conf.py
    • Search for version = and set version = "0.11.0"
    • Search for release = and set release = "0.11.0"
    • Save and exit
    • git add setup.py docs/conf.py

  • 6: Update version and dependencies (FOQUS) (N/A)

  • 7: Update version (IDAES) (N/A)

  • 8: Update version (IDAES examples) (N/A)

  • 9: Update version (IDAES examples-pse) (N/A)

  • 10: Update version and dependencies in ./setup.py (PARETO) (N/A)

  • 11: Check that the local modifications to the version are as they should

    git status      # there shouldn't be any other unstaged files
git status -vv  # the changes with the version should be there

  • 12: Commit the changes to the 0.11_rel branch

    # check that we're on the correct release branch
test "$(git branch --show-current)" = "0.11_rel" && git commit -m "0.11.0"

  • 13: Review the changes before pushing

    git log --oneline -n 5  # it should show only one commit which is not pushed
git push --set-upstream [email protected]:watertap-org/watertap.git "0.11_rel" --dry-run

  • 14: Push the changes

    git push --set-upstream [email protected]:watertap-org/watertap.git "0.11_rel"

Updating default branch with next dev version (N/A)

Creating the GitHub release

  • 1: Generate release notes and create GitHub draft release Copy and paste the following release notes into a file named release-notes-0.11.0.md:

    # 0.11 Release

Start with our [online documentation](https://watertap.readthedocs.org/en/0.11.0) to get started with install instructions, examples, etc.

## WaterTAP 0.11.0 Release Highlights

    Or, run the following shell command to create the file in the local directory:

    cat <<'EOF' > release-notes-0.11.0.md
# 0.11 Release

Start with our [online documentation](https://watertap.readthedocs.org/en/0.11.0) to get started with install instructions, examples, etc.

## WaterTAP 0.11.0 Release Highlights


EOF

    Run this command to create a draft release using the gh CLI tool

    gh release create "0.11.0" --repo "watertap-org/watertap" --target "0.11_rel" --title "0.11 Release" --notes-file "release-notes-0.11.0.md" --draft

  • 2: Create a ZIP file for the examples and attach it to the release as an asset (N/A)

  • 3: Update the compatibility file on main (N/A)

  • 4: Check that the GitHub release was created successfully

  • 5: Check that the release tag has been created in the repo

    curl -sL https://github.com/watertap-org/watertap/archive/0.11.0.zip | sha256sum

    NOTE

    • The release needs to be undrafted for this to work
    • Use wget if curl -sL doesn't work

Deleting the release (if needed)

  • 1: Delete the release on GitHub

    # add the --yes flag to skip confirmation prompt
gh release delete --repo watertap-org/watertap "0.11.0"

  • 2: Delete the tag on the remote

    pushd "$(mktemp -d)"
git clone --depth 1 --branch "0.11_rel" https://github.com/watertap-org/watertap && cd watertap
git push --delete [email protected]:watertap-org/watertap.git "refs/tags/0.11.0"

  • 3: Delete the tag locally

    git tag --delete "0.11.0"

Checking the docs (ReadTheDocs)

  • 1: Check the ReadTheDocs build

  • 2: Check that the 0.11.0 tag is available on ReadTheDocs

    • Manually, at https://watertap.readthedocs.org/en/0.11.0
    • curl -sL "https://watertap.readthedocs.org/en/0.11.0" | grep "/0.11.0/"
    • curl -sL "https://watertap.readthedocs.org/en/0.11.0" | grep "Versions" --after 10 | grep "/0.11.0/"

  • 3: Check that the ReadTheDocs revision (commit) on latest matches the release tag

    curl -sL "https://watertap.readthedocs.org/en/0.11.0" | grep "Revision"
curl -sL "https://watertap.readthedocs.org/en/latest" | grep "Revision"
curl -sL "https://watertap.readthedocs.org" | grep "Revision"

  • 4: Check that the ReadTheDocs revision (commit) on stable matches the release tag

    curl -sL "https://watertap.readthedocs.org/en/0.11.0" | grep "Revision"
curl -sL "https://watertap.readthedocs.org/en/stable" | grep "Revision"

Creating the watertap Python package distribution

  • 1: In a clean directory, clone the repo and switch to the release branch

    pushd "$(mktemp -d)"
git clone --depth 1 --branch "0.11_rel" https://github.com/watertap-org/watertap && cd watertap
# check that the branch is at the 0.11.0 tag
git tag --list | grep "0.11.0"

  • 2: Create a new Conda environment for building the package and activate it

    # bash/zsh
_build_env_name="build-watertap-0.11.0"
conda create --yes python=3.11 pip setuptools wheel twine --name "$_build_env_name" && conda activate "$_build_env_name"
# test that the pip executable is the one from the environment
which pip | grep "$_build_env_name"

  • 3: Install the package (NO EDITABLE MODE)

    pip install --no-cache-dir .

  • 4: Check that the installed package has the proper tags

    pip list | grep "0.11.0"
pip show watertap | grep "0.11.0"

  • 5: Run "smoke tests" for the installed package (once uploaded to PyPI, IT CANNOT BE DELETED!)

    pushd "$(mktemp -d)" && { pip install "watertap[testing]" && pytest --pyargs watertap ; } ; popd

  • 6: Remove large directories to avoid exceeding size limits (N/A)

  • 7: Build the sdist and bdist_wheel distributions

    python setup.py sdist bdist_wheel

  • 8: Check that the directory size is below PyPI's maximum

    ls -lh dist/*
_maxsize=100000  # 100 MB
_dirsize=$(du -s dist/ | cut -f 1) ; echo $_dirsize
[ "$_dirsize" -lt "$_maxsize" ]

  • 9: Upload the distributions to the test PyPI

    # bash/zsh
# assumes that the ~/.pypirc config file exists and defines the "testpypi" repository
grep "\[testpypi\]" ~/.pypirc && twine upload --repository testpypi dist/*

    NOTE It might take a while for the uploaded package to become available for pip install

  • 10: Test package from test PyPI in a dedicated temp Conda environment

    _test_env_name="test-watertap-0.11.0"
conda create --yes python=3.11 --name "$_test_env_name" && conda activate "$_test_env_name"
which pip | grep "$_test_env_name"
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple "watertap==0.11.0"
pushd "$(mktemp -d)" && { pip install "watertap[testing]" && pytest --pyargs watertap ; } ; popd
conda deactivate && conda env remove --name "$_test_env_name"

  • 11: Upload the distributions to the real PyPI

    conda activate "$_build_env_name"
# assumes that the ~/.pypirc config file exists and defines the "realpypi" repository
grep "\[realpypi\]" ~/.pypirc && twine upload --repository realpypi dist/*

    NOTE It might take a while for the uploaded package to become available for pip install

  • 12: Install package from real PyPI and generate requirements/environment files

    # bash/zsh
_rel_prefix="watertap-0.11.0"
_env_name="${_rel_prefix}-env"
_conda_file_name="environment-${_rel_prefix}.yml"
_pip_file_name="requirements-${_rel_prefix}.txt"
conda create --yes python=3.11 --name "$_env_name" && conda activate "$_env_name"
which pip | grep "$_env_name"
pip install "watertap==0.11.0"
pushd "$(mktemp -d)"
conda env export -n "$_env_name" -f "$_conda_file_name"
pip freeze > "$_pip_file_name"
gh release upload "0.11.0" "$_conda_file_name" "$_pip_file_name" --repo "watertap-org/watertap"
conda deactivate && popd

Build and deploy examples using containers (N/A)

Build and deploy examples (N/A)

Collect environment info for the release

  • 1: Install from PyPI

    # bash/zsh
_rel_prefix="watertap-0.11.0"
_env_name="${_rel_prefix}-env"
_conda_file_name="environment-${_rel_prefix}.yml"
_pip_file_name="requirements-${_rel_prefix}.txt"
conda create --yes python=3.11 --name "$_env_name" && conda activate "$_env_name"
which pip | grep "$_env_name"
pip install "watertap==0.11.0"

  • 2: Save environment info

    pushd "$(mktemp -d)"
conda env export --no-builds -n "$_env_name" -f "$_conda_file_name"
pip freeze > "$_pip_file_name"
cat "$_conda_file_name" "$_pip_file_name"

  • 3: Upload as GitHub release assets

    gh release upload "0.11.0" "$_conda_file_name" "$_pip_file_name" --repo "watertap-org/watertap"
conda deactivate && conda env remove -n "$_env_name" && popd

  • 4: Check that the assets are available

Announce the release

For WaterTAP developers

Software Engineering

Clone this wiki locally