Release Process

This is a guide to the process of creating a new release, and is meant for the maintainers of Raster Vision.

Note

The following instructions assume that Python 3 is the default Python on your local system. Using Python 2 will not work.

Minor or Major Version Release

  1. It’s a good idea to update any major dependencies before the release.

  2. Fix any broken badges on the Github repo readme.

  3. Update the docs to reflect all changes since last release. You can view a local copy of the docs by running docker/run --docs and then viewing localhost:8000.

  4. Update tiny_spacenet.py if needed and copy its contents to the index, Quickstart, and Github repo readme.

  5. Update Changelog, and point out config API changes.

  6. Test out Setup and Quickstart instructions and make sure they work.

  7. Test examples from Writing pipelines and plugins, Bootstrap new projects with a template, and Setup AWS Batch using CloudFormation.

    rastervision run inprocess rastervision.pipeline_example_plugin1.config1 -a root_uri /opt/data/pipeline-example/1/ -s 2
rastervision run inprocess rastervision.pipeline_example_plugin1.config2 -a root_uri /opt/data/pipeline-example/2/ -s 2
rastervision run inprocess rastervision.pipeline_example_plugin2.config3 -a root_uri /opt/data/pipeline-example/3/ -s 2

    cookiecutter /Users/lfishgold/projects/raster-vision/cookiecutter_template

  8. Run all Examples and check that evaluation metrics are close to the scores from the last release. (For each example, there should be a link to a JSON file with the evaluation metrics from the last release.) This stage often uncovers bugs, and is the most time consuming part of the release process. There is a script to help run the examples and collect their output in rastervision.pytorch_backend.examples.test. There are the following subcommands: run to run sets of examples remotely or locally, collect to download certain files generated by running examples to aide inspection, and predict to run the predict command on example model bundles. To use this script, you will need to follow certain conventions around file organization which will be apparent in the cfg dictionary in the source code for test.py.

  9. Collect all model bundles, and check that they work with the predict command and sanity check output in QGIS.

  10. Update the Model Zoo by uploading model bundles and sample images to the right place on S3. If you use the collect command (described above), you should be able to sync the collect_dir to s3://azavea-research-public-data/raster-vision/examples/model-zoo-<version>.

  11. Update the version number. This occurs in many, many places, so it’s best to do this with a find and replace over the entire repo.

  12. Make a PR to the master branch with the preceding updates. In the PR, there should be a link to preview the docs. Check that they are building and look correct.

  13. Make a git branch with the version as the name, and push to Github.

  14. Ensure that the docs are building correctly for the new version branch on readthedocs. You will need to have admin access on your RTD account. Once the branch is building successfully, Under Versions -> Activate a Version, you can activate the version to add it to the sidebar of the docs for the latest version. (This might require manually triggering a rebuild of the docs.) Then, under Admin -> Advanced Settings, change the default version to the new version.

  15. Travis CI is supposed to publish an image whenever there is a push to a branch with a version number as the name. If this doesn’t work or you want to publish it immediately, then you can manually make a Docker image for the new version and push to Quay. For this you will need an account on Quay.io under the Azavea organization.

    ./docker/build
docker login quay.io
docker tag raster-vision-pytorch:latest quay.io/azavea/raster-vision:pytorch-<version>
docker push quay.io/azavea/raster-vision:pytorch-<version>

  16. Make a Github tag and release using the previous release as a template.

  17. Publish all packages to PyPI. This step requires twine which you can install with pip install twine. To store settings for PyPI you can setup a ~/.pypirc file containing:

    [pypi]
username = azavea

    Once packages are published they cannot be changed so be careful. (It’s possible to practice using testpypi.) Navigate to the raster-vision repo on your local filesystem. With the version branch checked out, run something like the following to publish each plugin, and then the top-level package.

    export RV="/Users/lfishgold/projects/raster-vision"

cd $RV/rastervision_pipeline
python setup.py sdist bdist_wheel
twine upload dist/*

cd $RV/rastervision_aws_batch
python setup.py sdist bdist_wheel
twine upload dist/*

cd $RV/rastervision_aws_s3
python setup.py sdist bdist_wheel
twine upload dist/*

cd $RV/rastervision_core
python setup.py sdist bdist_wheel
twine upload dist/*

cd $RV/rastervision_pytorch_learner
python setup.py sdist bdist_wheel
twine upload dist/*

cd $RV/rastervision_pytorch_backend
python setup.py sdist bdist_wheel
twine upload dist/*

cd $RV/rastervision_gdal_vsi
python setup.py sdist bdist_wheel
twine upload dist/*

cd $RV
python setup.py sdist bdist_wheel
twine upload dist/*

  18. Announce new release on Gitter, and with blog post if it’s a big release.

Bug Fix Release

This describes how to create a new bug fix release, using incrementing from 0.8.0 to 0.8.1 as an example. This assumes that there is already a branch for a minor release called 0.8.

  1. To create a bug fix release (version 0.8.1), we need to backport all the bug fix commits on the master branch that have been added since the last bug fix release onto the 0.8 branch. For each bug fix PR on master, we need to create a PR against the 0.8 branch based on a branch of 0.8 that has cherry-picked the commits from the original PR. The title of the PR should start with [BACKPORT].

  2. Make and merge a PR against 0.8 (but not master) that increments the version in each setup.py file to 0.8.1. Then wait for the 0.8 branch to be built by Travis and the 0.8 Docker images to be published to Quay. If that is successful, we can proceed to the next steps of actually publishing a release.

  3. Using the Github UI, make a new release. Use 0.8.1 as the tag, and the 0.8 branch as the target.

  4. The image for 0.8 is created automatically by Travis, but we need to manually create images for 0.8.1. For this you will need an account on Quay under the Azavea organization.

    docker login quay.io

docker pull quay.io/azavea/raster-vision:pytorch-0.8
docker tag quay.io/azavea/raster-vision:pytorch-0.8 quay.io/azavea/raster-vision:pytorch-0.8.1
docker push quay.io/azavea/raster-vision:pytorch-0.8.1

  5. Publish the new version to PyPI. Follow the same instructions for PyPI that are listed above for minor/major version releases.