Creating a Release

This section aims to help you do a SpyDrNet-TMR release, meaning you make the latest code and documentation available. The steps are listed in what seems to be the best order of operation. Steps which need more explanation are highlighted below.

  1. Merge each contributors’ branches into one branch (the ‘next_release’ branch)

  2. Run git merge main while the next_release branch is checked out.

  3. Update the Release Notes and git commit release notes

  4. Update the Documentation and ensure it can build properly

  5. On Github, create a pull request with the updated code in the next_release branch.

  6. Accept and merge the pull request when the checks have finished.

  7. Move to the main branch using git checkout main

  8. Update the tag

  9. Build the Python Package (this will update the documentation’s version number)

  10. Build the Documentation

  11. Create a Github Release

  12. Publishing the documentation

Update the Release Notes

The release notes file called RELEASE.rst should be updated to outline what changes/fixes are in the new release. The date, version number, and other information should all be included.

SpyDrNet-TMR uses a Major.Minor.Bug versioning scheme where minor version updates do not break the existing API and major version updates may break it. Bug fixes do not add substantial new functionality, but rather fix broken functionality.

Update the Documentation

Sphinx pulls from doc strings as well as .rst files to build documentation. The documentation is built using a makefile in the docs folder.

Before building the documentation run make clean to clear away the old files.

Before proceeding, ensure that both of the following are successful (make sure they execute without errors. Try to minimize the warnings as well):

>>> make html

and

>>> make latexpdf

If you are missing packages run:

>>> make install

You may also need to run sudo apt install latexmk and apt install texlive-latex-extra to be able to create the pdf file.

The generated files can be found in the build folder. Take a look at them and make sure everything looks good. Later, these commands will be run again, and the html files put online and pdf files added to the Github release files.

Update the tag

Be sure you are on the main branch.

Tags are used to label the release. When all changes are merged into the main branch, create a new tag. In the examples below, replace 1.0.0 with the version number you are releasing.

To see the current version number

>>> git describe

Creation

>>> git tag -a v1.0.0 -m "SpyDrNet-TMR 1.0.0"

Push your changes to the tags

>>> git push --tags

A tag may need to be updated if a new commit is pushed to the branch (because the tag will be left on the previous commit) or if you simply mess up. Do the following to force update the tag.

Updating

>>> git tag -a v1.0.0 -m "SpyDrNet-TMR 1.0.0" -f

>>> git push --tags -f

Build the Python Package

Upgrade pip if needed.

>>> python3 -m pip install --upgrade pip

Make sure everything is up to date

>>> python3 -m pip install --user --upgrade setuptools wheel

Make the python archive package:

>>> python3 setup.py sdist bdist_wheel

The build files will be stored in the following directories

spydrnet-tmr/build and spydrnet-tmr/dist

Build the Documentation

Make sure you are in the docs directory

>>> cd docs

then run the followings to build the documentation:

>>> make clean
>>> make latexpdf
>>> make html

Make sure that each one executes and doesn’t have errors. Try to minimize the warnings as well.

Create a Github Release

Releases can be created on Github. On the releases tab, draft a new release. Select the new tag you just created (it should have the release number).

The release should be named SpyDrNet-TMR 1.0.0 where 1.0.0 is replaced with the proper release number.

Enter a description–it could just be a reiteration of the release notes or other relevant information.

Three files need to be added as assets to the new release:

The two files that were generated during Build the Python Package (a tar.gz file and a .whl file).

The Reference PDF - download the spydrnet_tmr_reference.pdf found in the docs/latex folder. Rename it to spydrnet_tmr_reference-new_release_number.pdf. If the pdf file doesn’t exist, run make latexpdf in the /docs folder again.

Publishing the documentation

This is easiest on Linux (or at least not Windows, MacOS works fine as well)

Make sure you are still on the main branch and that everything in the html folder is up-to-date. If not, re-run the instructions in Build the Documentation.

Checkout the gh-pages branch create a new folder with the release number as the name. Move the docs/build/html folder into the newly created folder. Make sure to delete the html folder after you are finished.

(If html folder doesn’t contain the latest pages, it could be that the html folder wasn’t deleted from the previous release, delete the folder, commit the changes and repeat the steps above)

The documentation is built from the stable link so the stable link will need to be updated to point to the newly updated documentation.

Check which version of the documentation the stable link points to

>>> ls -lha

to update the stable link, remove it first (watch syntax here very carefully, a terminating could make the command delete the folder’s contents instead of the link)

>>> rm stable

then create a link to the new folder

>>> ln -s version.number stable

run git add to add the newly created folder and the stable link

push your changes to the git repository, just to the ghpages branch.

The new documentation should show up online now.