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

• Go to the tests/recordings folder and delete the old recordings. Make new recordings by setting the test mode to 'Record'. 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. If you're updating docs for the first time, ensure that your local gh-pages branch correctly tracks the remote gh-pages branch and does not mistakenly contain the history of the dev branch.
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:

>python3 setup.py sdist
>python3 setup.py bdist_wheel

This will create the source distribution file (.tar.gz) in the /dist folder and the universal wheel file (.whl) that works for both Python 2.x and 3.x.

If you get an general error when creating the wheel, make sure that your setup.py files don't have a Unicode BOM and then re-run the original setup.py file.

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, first test locally, then upload and test installing from the test server, before finally upload and test from the production server.

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 in your home directory:

[distutils]
index-servers =
  pypi
  test

[pypi]
username=<yourusername>
password=<yourpassword>

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

Test server

To upload the library to the test server run:

>twine upload -r test dist/*.tar.gz
>twine upload -r test dist/*.whl

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

>pip3 install twine

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. Basically venv creates a directory where all the packages could be installed. The directory also contains different python and pip versions. In the virtual environment, you can install from a local file, from the test server, or real server. See below for an example.

Python virtual environment

Python 3:

>mkdir py3test
>cd py3test
>python3 -m venv .
<Validate the library. See below.>

Python 2:

>virtualenv py2test
>cd py2test
<Validate the library. See below.>

Validate the library

>bin/pip3.6 install azure-common
>bin/pip3.6 install python-dateutil
>bin/pip3.6 install requests
>bin/pip3.6 install cryptography
>bin/pip3.6 install azure-storage -i https://test.pypi.org/legacy/ --no-deps

$ bin/python3
Python 3.6.1 (v3.6.1:69c0db5050, Mar 21 2017, 01:21:04)
[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>import azure.storage
>>>account = azure.storage.CloudStorageAccount("accountName", "accountKey")
>>> bs = account.create_block_blob_service()
>>> bs.create_container("testy")
True
>>> bs.delete_container("testy")
True
>>> print("This is the version " + azure.storage.__version__)
This is the version 0.34.3
>>>

Production

To upload the library to production server run:

>twine upload dist\*.tar.gz
>twine upload dist\*.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 [email protected]