Making Releases

This page is for RenderToolbox3 team members who want to make RenderToolbox3 releases. A "release" represents a certain amount of progress made with the RenderToolbox3 code and documentation, plus repository tags that capture the state of the code and documentation with a name like v2.0.

You must be a RenderToolbox3 team member in order to make a release. This means you must have permission to push changes to the RenderToolbox3 repositories. This also means you must have access to the "Rhino" computing cluster that RenderToolbox3 team uses for generating reference data.

Overview

Let's assume that you've already set goals for your release using the GitHub issue Tracker and that you've reached them all, and now you're ready to make a new release that captures the state of the code and documentation with the name v2.0. You should create the following repository tags:

• v2.0, for the RenderToolbox3 main repository master branch
• v2.0-docs, for the RenderToolbox3 main repository gh-pages branch
• v2.0-wiki, for the RenderToolbox3 GitHub wiki repository master branch

Read on for some details and tips about creating each tag.

epic-scene-test.sh

The epic-scene-test.sh script will generate reference renderings in two steps. First, the script will invoke Matlab on the Rhino head node in order to create renderer-native scene files. This must be done on the head node because the Mitsuba Collada importer requires OpenGL. Then, the script will render all of the renderer-native scene files using the Rhino worker nodes. It will store the outputs at

/home2/brainard/render-toolbox-3/epic-scene-test/temp
/home2/brainard/render-toolbox-3/epic-scene-test/data
/home2/brainard/render-toolbox-3/epic-scene-test/images

Once the renderings are generated, you should compare them to the existing Reference Renderings and make sure that nothing has changed in a majorly bad way. Use the CompareAllExampleScenes() function.

v2.0, v2.0-docs, and v2.0-wiki

The remaining tags capture the state of the main RenderToolbox3 GitHub project:

• v2.0 captures the state of the RenderToolbox3 code in the main repository master branch.
• v2.0-docs captures the state of the RenderToolbox3 HTML function reference main repository gh-pages branch.
• v2.0-wiki captures the state of the RenderToolbox3 wiki documentation in the wiki repository master branch

The create-release-tags.sh shell script can create all of these tags automatically. This script can be run from any machine, and is part of the RenderToolbox3 source code:

Utilities/create-release-tags.sh

Before you run this script, you should edit it to specify the name of your RenderToolbox3 release and a working folder where it can clone repositories:

RTB_VERSION="v2.0"
WORKING_FOLDER="/Users/myUserName/RenderToolbox3-release-temp"

You might also need to change other constants defined near the top of the script.

The script will create a new v2.0 tag for the RenderToolbox3 master branch.

Then it will regenerate the HTML function reference docs based on code comments that are in the master branch, using Doxygen. It will store the fresh HTML docs in the gh-pages branch and create a v2.0-docs tag. The gh-pages branch is a special GitHub branch that allows docs to be served on the web. See the result.

Finally, the script will create a v2.0-wiki tag in the RenderToolbox3 GitHub wiki repository. This repository is separate from the main RenderToolbox3 code repository. The script does not update the wiki at all, it just creates a tag to go along with the other release tags. If you need to update the wiki for your release, you should do so before running create-release-tags.sh.

Fixing Mistakes

If you make a mistake, or you need to include new changes in your release, you can re-create any of the tags above.

epic-scene-test.sh and replace-gitub-reference-data.sh always replace old outputs with new outputs, so it should not matter how many times you re-execute them.

create-release-tags.sh forces tags to be updated, so even if you've already created a tag like v2.0, you can re-execute the script to have the tag updated to reflect new changes.

You should only re-create your tags for small changes, like silly bug fixes or typos. If you make any larger changes, you should capture them with a new release. Release names like v2.1 and v2.0.1 come cheap and won't hurt anyone.