Committer Guide

    This section outlines steps which need to be completed by new team members andis indented for people who have been voted to join Libcloud project as acommitter and / or PMC member. It also assumes you have already filledyour ICLA and your Apache account has been created.

    First congratulations and welcome to the team!

    If you haven’t yet, subscribe to {dev,users,notifications}@libcloud.apache.orgmailing lists. Notifications mailing list is especially important because all ofGithub Issue, Pull Request and build notifications are sent there.

    2. Subscribe to the private mailing list

    Subscribe to by sending an email toprivate-subscribe@libcloud.apache.org. Keep in mind that this list is privateand your subscription needs to be approved by a moderator.

    3. Create PyPi account

    Creating a PyPi account by going to and send an email toprivate@libcloud.apache.org requesting to be added as a maintainer to package.Make sure to select a strong and unique password ( is yourfriend).

    After you have registered go to“Your details” page andpopulate PGP Key ID field with your PGP key ID.

    4. Link your ASF and Github account

    We use Github for managing issues and user contributions (pull requests). Assuch, you need to link your Github.com account with your ASF account using. This way you will get writeaccess to github.com/apache/libcloud repository and you will be able tomanage issues and pull request directly through our Github repository.

    When a pull request with user contribution (changes) has been reviewed andall the criteria for merging has been met (tests and code coverage, Travisbuild is passing, user signed an ICLA, etc.), you can directly merge thosechanges into trunk either by using Github web interface or doing it manuallyon the command line.

    It’s also important that you update changelog in CHANGES.rst file afteryou merged the changes.

    This section contains information a release manager should follow whenpreparing a release.

    0. Update committed files

    • Make sure CHANGES file is up to date
    • Make sure version string in libcloud/init.py is up to date
    • Make sure version and release in docs/conf.py are up to date
    • Update constants, pricing and other auto-generated data: tox -e scrape-ec2-sizes,scrape-ec2-prices

    1. Pre-release check list

    • Make sure tests pass on all the supported Python versions (tox)
    • Remove the tox directory with
    • Remove the secrets file with rm libcloud/test/secrets.py
    • Remove leftover builds from previous releases. rm -f dist/apache* ; rm -rf apache_libcloud.egg-info
    • Create a new Github milestone for the release in question (if one doesn’t existyet)
    • Update affected issues and pull requests and add the corresponding releasemilestone to them

    3. Creating release artifacts

    We have a script that runs the required setup.py commands and then hashesand signs the files. You will need the latest version of pip and the wheelpackage. To run it:

    -u argument will be used to find a key with a matching email address inyour local GPG database.

    This should result in a set ofapache-libcloud-${VERSION}.{tar.bz2,tar.gz,zip,whl}{,asc,md5,sha1} files thatare suitable to be uploaded for a release.

    Copy the artifacts in another directory, unpack one of them and test it with tox.

    4. Tagging a release

    Tag the tentative release with a -tentative postfix.

    1. git tag <version> <commit hash>
    1. git tag --sign v0.15.0-tentative 105b9610835f99704996d861d613c5a9a8b3f8b1

    5. Upload the release artifacts and start a [VOTE] thread

    Upload all release artifacts including the whl files to your people.apache.orgspace. Then start a [VOTE] thread on the dev@libcloud.apache.org mailing list.

    Once the vote has passed tag the release with a new tag, removing the -tentative postfix.Upload the release artifacts to Apache servers and Pypi.

    For example:

    1. git tag --sign v0.15.0 105b9610835f99704996d861d613c5a9a8b3f8b1

    The commit SHA needs to be the one release artifacts are based on (aka the onepeople voted on) and the same one you used for the tag.

    Keep in mind that it’s important that you sign the commit / tag with your GPGkey.

    6. Uploading release artifacts to Apache servers

    • Add release artifacts to the dist SVN repository at

    It may take up to a day for the artifacts to be available on all theApache mirrors, but they should be instantly available athttp://www.apache.org/dist/libcloud/.

    • If there is more than one old release in the repository, delete rest of theold release and only leave current and previous release there. Old releasesare automatically archived and available at.

    7. Publishing package to PyPi

    We have a script that runs uploads the signed Python source files to PyPi. It uses twine, so ensureyou have twine available in your path which twine before running. Twine can be downloaded from https://pypi.python.org/pypi/twine

    1. cd dist
    2. ./deploy.sh

    Once all the files have been uploaded, the page should look similar to thescreenshot below.

    To verify that nothing went wrong doing the release process, run the./dist/verify_checksums.sh script.

    This script downloads the release artifacts from the Apache and PyPi server andmakes sure that the MD5 check sums of the both files match.

    Usage:

    For example

    1. ./dist/verify_checksums.sh apache-libcloud-0.13.2

    9. Updating doaplibcloud.rdf, _init.py

    Add information about the new release to the doap_libcloud.rdf file in theroot of the main code repository.

    Update version attribute in libcloud/init.py file and indicatewe are now working on a new release by incrementing a number and adding -devsuffix. For example, if version 2.2.1 has been released you would changeit from:

    1. __version__ = '2.2.1'

    To:

    1. __version__ = '2.2.2-dev'

    10. Updating website

    • Update the front page (source/index.html file)
    • Update “Downloads” page (source/downloads.md file)
    • Add a blog entry in the _posts directory.

    Build the site locally and make sure everything is correct. Check the file.

    11. Sending announcements

    • Send a release announcement to {dev,users}@libcloud.apache.org. If it’s amajor release also send it to announce@apache.org.
    • Send a release announcement to Twitter and Google+

    Note: If the release fixes a security vulnerability, you should also sendinformation about a vulnerability to the following full disclosure mailinglists:

    The email you send should also be signed using your GPG key. You can findan example of such announcement on the .

    If needed, use Apache URL shortening service - http://s.apache.org/

    This section includes email templates which can be used when sending outofficial communication to the mailing lists.

    Release voting thread template

    This template should be used when starting a voting thread for a new release.

    Subject:

    1. [VOTE] Release Apache Libcloud <version>

    Body:

    For example:

    Subject:

    1. [VOTE] Release Apache Libcloud 0.13.2

    Body:

    1. This is a voting thread for Libcloud 0.13.2.
    2.  
    3. This is another primarily a bug-fix release. Previous release included a fix for the Content-Length bug which didn't fully fix the original issue. It missed out "raw" requests which are fixed in this release (LIBCLOUD-396).
    4.  
    5. This bug could manifest itself while uploading a file with some of the storage providers.
    6. Besides this bug fix, it includes a couple of other smaller bug fixes and changes. Full change log
    7. can be found at https://git-wip-us.apache.org/repos/asf?p=libcloud.git;a=blob;f=CHANGES;h=b7747f777afdeb63bcacf496d1d034f1b3287c31;hb=c4b3daae946049652a500a8515929b4cbf14a6b4
    8.  
    9. Release artifacts can be found at http://people.apache.org/~tomaz/libcloud/.
    10.  
    11. Please test the release and post your votes.
    12.  
    13. +/- 1
    14. [  ]  Release Apache Libcloud 0.13.2
    15.  
    16. Vote will be opened until September 18th, 2013 (or longer, if needed).
    17.  
    18. Thanks,
    19. Tomaz

    Release announcement

    This template should be used when sending out a release announcement.

    Subject:

    1. [ANNOUNCE] Apache Libcloud 0.13.1 release

    Body:

    1. Libcloud is a Python library that abstracts away the differences among
    2. multiple cloud provider APIs. It allows users to manage cloud services
    3. (servers, storage, loadbalancers, DNS) offered by many different providers
    4. through a single, unified and easy to use API.
    5.  
    6. We are pleased to announce the release of Libcloud <version>!
    7.  
    8. <short description of the release which should include release highlights>
    9.  
    10. Full change log can be found at <link to CHANGES file for this release>
    11.  
    12. Download
    13.  
    14. Libcloud <version> can be downloaded from http://libcloud.apache.org/downloads.html
    15. or installed using pip:
    16.  
    17. pip install apache-libcloud
    18.  
    19. Upgrading
    20.  
    21. If you have installed Libcloud using pip you can also use it to upgrade it:
    22.  
    23. pip install --upgrade apache-libcloud
    24.  
    25. Upgrade notes
    26.  
    27. A page which describes backward incompatible or semi-incompatible
    28. changes and how to preserve the old behavior when this is possible
    29. can be found at http://libcloud.apache.org/upgrade-notes.html.
    30.  
    31. Documentation
    32.  
    33. API documentation can be found at http://libcloud.apache.org/apidocs/<version>/.
    34.  
    35. We also have a new Sphinx documentation which can be found at https://libcloud.apache.org/docs/.
    36.  
    37. Bugs / Issues
    38.  
    39. If you find any bug or issue, please report it on our issue tracker
    40. <https://github.com/apache/libcloud/issues>.
    41. Don't forget to attach an example and / or test which reproduces your problem.
    42. Thanks
    43.  
    44. Thanks to everyone who contributed and made this release possible! Full list of
    45. people who contributed to this release can be found in the CHANGES file
    46. <link to the changes file for this release>.

    For example:

    Body:

    1. Libcloud is a Python library that abstracts away the differences among
    2. multiple cloud provider APIs. It allows users to manage cloud services
    3. (servers, storage, loadbalancers, DNS) offered by many different providers
    4. through a single, unified and easy to use API.
    5.  
    6. We are pleased to announce the release of Libcloud 0.13.1!
    7.  
    8. This is a bug-fix only release. Among some smaller bugs it also fixes
    9. Content-Length regression which broke create and update operations in
    10. the Bluebox Compute and Azure Storage driver (LIBCLOUD-362, LIBCLOUD-3901).
    11.  
    12. Full change log can be found at <https://git-wip-us.apache.org/repos/asf?p=libcloud.git;a=blob;f=CHANGES;h=ca90c84e296ca82e2206eb86ed7364c588aad503;hb=602b6a7a27dca6990a38eb887e1d6615826387d5>
    13.  
    14. Download
    15.  
    16. Libcloud 0.13.1 can be downloaded from http://libcloud.apache.org/downloads.html
    17. or installed using pip:
    18.  
    19. pip install apache-libcloud
    20.  
    21. Upgrading
    22.  
    23. If you have installed Libcloud using pip you can also use it to upgrade it:
    24.  
    25. pip install --upgrade apache-libcloud
    26.  
    27. Upgrade notes
    28.  
    29. A page which describes backward incompatible or semi-incompatible
    30. changes and how to preserve the old behavior when this is possible
    31. can be found at http://libcloud.apache.org/upgrade-notes.html.
    32.  
    33. Documentation
    34.  
    35. API documentation can be found at http://libcloud.apache.org/apidocs/0.13.1/.
    36.  
    37. We also have a new Sphinx documentation which can be found at https://libcloud.apache.org/docs/.
    38. Keep in mind though, that this documentation reflects state in trunk which
    39. includes some backward incompatible changes which aren't present in 0.13.1.
    40. All the examples in the documentation which only work with trunk are clearly marked with a note.
    41.  
    42. Bugs / Issues
    43.  
    44. If you find any bug or issue, please report it on our issue tracker
    45. <https://github.com/apache/libcloud/issues>.
    46. Don't forget to attach an example and / or test which reproduces your problem.
    47.  
    48. Thanks
    49.  
    50. Thanks to everyone who contributed and made this release possible! Full list of
    51. people who contributed to this release can be found in the CHANGES file