Release Process

Code changes

Update the version in the following files.

/setup.py
/azure/storage/_constants.py

The documentation configuration has two strings for version and release

/doc/conf.py

The change logs/

/ChangeLog.md
/BreakingChanges.md

Tests

Test modes are configured in tests/settings_real.py

• Make new recordings. The test recordings include the version number in the User-Agent header of each request as well as the service version in the x-ms-version header. Make sure to run the tests under Python 3.x when recording as there are some issues in 2.x.
• Run the tests in Playback mode after recording to make sure the recording succeeded.
• Run the tests using Python 2.x in RunLiveNoRecord mode to verify the library is backwards compatible.

GitHub Release

• Do a pull request from dev to master.
• Create a new release, set the contents to the change log entry for the new version.

Docs

Azure Documentation

Update the Python samples and the Azure.com Python articles, if necessary.

ReadTheDocs

• Trigger rebuild of readthedocs.org. This should happen as part of a push, but if not you can go to ReadTheDocs and trigger a build manually.

• ReadTheDocs is currently having build issues for our code. So, as a stop-gap, we're publishing to GitHub.io. To publish the docs to GitHub.io:

1. Build the docs using doc/BuildDocs.bat. Copy the output from the doc/_build/html folder to elsewhere.
2. In your local copy of the public repo, switch to the gh-pages branch and make sure it is up to date with the public repo.
3. Paste the contents of the html folder into the gh-pages branch.
4. Commit the changes and do a pull request to the public repo. After a couple minutes, the updates should appear on GitHub.io.

Pip Release

Run the following commands to build from the base azure-storage-python folder:

c:\python34\python setup.py sdist
cd dist
c:\python27\python -m pip wheel --no-index --no-deps <filename>.zip
c:\python34\python -m pip wheel --no-index --no-deps <filename>.zip

This will create the source distribution file in the /dist folder and the wheel files for Python 2.x and 3.x in the /dist/wheelhouse folder.

If you get an general error when creating the wheel, make sure that your setup.py files don't have a Unicode BOM.

Python Package Index

Once you've uploaded to PyPI, there's no way to overwrite the package. In case of problems, you'll need to increment the version number. To make sure everything works fine, upload and then test installing from the test server first.

Pypi Setup

• Create an account on the production server.
• Create an account on the test server with the same username/password.
• Get added as a project owner for azure-storage for both prod & test environments.
• Create a .pypirc file:

[distutils]
index-servers =
  pypi
  test

[pypi]
repository=https://pypi.python.org/pypi
username=<yourusername>
password=<yourpassword>

[test]
repository=https://testpypi.python.org/pypi
username=<yourusername>
password=<yourpassword>

Test server

To upload the library to the test server run:

c:\python34\scripts\twine upload -r test dist\*.zip
c:\python34\scripts\twine upload -r test dist\wheelhouse\*.whl

Note: If you don't have twine, run:

pip install twine

Make sure you already have the dependencies installed, as they may not be found on the test server. To install from the test server:

pip install azure-storage -i https://testpypi.python.org/pypi --no-deps

Pip Cache

Beware of the pip cache! If you see a message like this while testing installation of the package you've uploaded to pip:

Using cached azure_storage-0.20.0-py2.py3-none-any.whl

Then delete the %localappdata%/pip folder and test again.

Test Locally

Test locally using both Python 2 and Python 3. The virtual environments should help you localize problems.

Python 3 virtual environment

mkdir py3test
cd py3test
py -3.4 -m venv env
env\scripts\activate
<Validate the library>
deactivate

Python 2 virtual environment

mkdir py2test
cd py2test
py -2.7 -m virtualenv venv
.\venv\Scripts\activate
<Validate the library>
deactivate

Validate the library

pip install azure-common
pip install python-dateutil
pip install requests
pip install azure-storage -i https://testpypi.python.org/pypi --no-deps

(env) C:\Projects\Temp\storage0203test>python
Python 3.4.1 (v3.4.1:c0e311e010fc, May 18 2014, 10:45:13) [MSC v.1600 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import azure.storage
>>> azure.storage.__version__
<verify the version is correct>
>>> exit()

Production

To upload the library to production server run:

c:\python34\scripts\twine upload dist\*.zip
c:\python34\scripts\twine upload dist\wheelhouse\*.whl

To install from production:

pip install azure-storage

Azure Bundle

The azure bundle package installs a specific version of the azure-storage package.

Contact the Azure SDK for Python team to update the azure bundle package. https://github.com/Azure/azure-sdk-for-python/wiki/Bundle-update-process

Publicity

• Post to python-announce-list@python.org