Release Process

This process describes the steps to execute the automated release workflow for vsgen. This workflow consists of:

1. A new release being generated on GitHub.
2. The release built and validated by AppVeyor.
3. The documentation updated on the Read the Docs.
4. The Python package updated on PyPI.

Prerequisites

1. Close all tickets for the next version.

2. Update the minimum version of all requirements in setup.py.

3. Update the exact version of all requirements in requirements.txt.

4. Run python setup.py test from the project root. All tests for all supported versions must pass:

   $ python setup.py test
   [...]
   ________ summary ________
   OK
   

5. Run python setup.py pep8 from the project root. All pep8 validations must pass:

   $ python setup.py pep8
   running pep8
   

6. Build the docs. While the final target is HTML there are additional steps to execute. Make sure there are no errors and undefined references.

   $ cd docs/
   $ pip install -r requirements.txt
   $ make.bat clean
   $ make.bat rst
   $ make.bat html
   $ make.bat view
   $ cd ..
   

7. Update the change log CHANGES.txt by reviewing the changes since last release on the github compare site or from the command line:

   $ for /f "delims=" %a in ('git describe --tags --abbrev^=0') do @git log %a..HEAD --oneline --decorate
   

8. Commit all changes:

   $ git commit -m 'Updated change log for upcoming release.'
   

Build

1. Build a source distribution and a wheel package and test them:

   $ python setup.py sdist bdist_wheel
   $ ls dist/
   vsgen-a.b.c-py2.py3-none-any.whl vsgen-a.b.c.tar.gz
   

2. Install the source distribution:

   Ensure clean state if ran repeatedly:

   $ rm -rf %TEMP%\vsgen-sdist
   

   Create a virtual environment and install the distribution:

   $ virtualenv %TEMP%\vsgen-sdist
   $ %TEMP%\vsgen-sdist\activate
   (vsgen-sdist) $ pip install .\dist\vsgen-a.b.c.zip
   (vsgen-sdist) $ python
   >>> import vsgen
   >>> vsgen.__version__
   'a.b.c'
   

3. Instal the wheel distribution:

   Ensure clean state if ran repeatedly:

   $ rm -rf %TEMP%\vsgen-wheel
   

   Create a virtual environment and install the distribution:

   $ virtualenv %TEMP%\vsgen-wheel
   $ %TEMP%\vsgen-wheel\activate
   (vsgen-wheel) $ pip install .\dist\vsgen-a.b.c-py2.py3-none-any.whl
   (vsgen-wheel) $ python
   >>> import vsgen
   >>> vsgen.__version__
   'a.b.c'
   

Release

1. Sync the local branch with the remote master branch and verify that the Appveyor dashboard is passing.
2. Navigate to vsgen’s release page and draft a new release:
   1. Give the release a title (Feature Release, Maintenance Release, etc.).
   2. Tag with the appropriate version as described in CHANGES.txt.
3. Publish the release:
   1. Verify that the Appveyor dashboard is green and has published the package to PyPI.
   2. Verify that the Read the Docs is updated.
4. Check if the package is displayed correctly: https://pypi.python.org/pypi/vsgen

Post release

Finally instal vsgen one last time:

Ensure clean state if ran repeatedly:

$ rm -rf %TEMP%\vsgen-pip

Create a virtual environment and install the distribution:

$ virtualenv %TEMP%\vsgen-pip
$ %TEMP%\vsgen-pip\activate
(vsgen-pip) $ pip install -U vsgen
(vsgen-pip) $ python
>>> import vsgen
>>> vsgen.__version__
'a.b.c'