Committer Guide =============== New committer guidelines ------------------------ .. note:: This section outlines steps which need to be completed by new team members and is indented for people who have been voted to join Libcloud project as a committer and / or PMC member. It also assumes you have already filled your ICLA and your Apache account has been created. First congratulations and welcome to the team! 1. Subscribe to the public mailing lists ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you haven't yet, subscribe to {dev,users,notifications}@libcloud.apache.org mailing lists. Notifications mailing list is especially important because all of Github Issue, Pull Request and build notifications are sent there. 2. Subscribe to the private mailing list ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Subscribe to private@libcloud.apache.org by sending an email to private-subscribe@libcloud.apache.org. Keep in mind that this list is private and your subscription needs to be approved by a moderator. 3. Create PyPi account ~~~~~~~~~~~~~~~~~~~~~~ Creating a PyPi account by going to https://pypi.python.org/pypi?%3Aaction=register_form and send an email to private@libcloud.apache.org requesting to be added as a maintainer to `apache-libcloud `_ package. Make sure to select a strong and unique password (``pwgen -s 48 1`` is your friend). After you have registered go to "`Your details `_" page and populate `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). As such, you need to link your Github.com account with your ASF account using `Gitbox `_. This way you will get write access to github.com/apache/libcloud repository and you will be able to manage issues and pull request directly through our Github repository. Merging user contributions -------------------------- When a pull request with user contribution (changes) has been reviewed and all the criteria for merging has been met (tests and code coverage, Travis build is passing, user signed an ICLA, etc.), you can directly merge those changes into trunk either by using Github web interface or doing it manually on the command line. It's also important that you update changelog in ``CHANGES.rst`` file after you merged the changes. Making a release (for release managers) --------------------------------------- This section contains information a release manager should follow when preparing 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 ``rm -rf .tox`` * 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`` 2. Update Github ~~~~~~~~~~~~~~~~~ * Create a new Github milestone for the release in question (if one doesn't exist yet) * Update affected issues and pull requests and add the corresponding release milestone to them 3. Creating release artifacts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: It's important that you have the latest versions of ``setuptools``, ``wheel`` and ``pip`` installed to ensure the generated wheel files contain correct metadata. We have a script that runs the required setup.py commands and then hashes and signs the files. You will need the latest version of ``pip`` and the ``wheel`` package. To run it: .. sourcecode:: bash cd dist ./release.sh -u @apache.org ``-u`` argument will be used to find a key with a matching email address in your local GPG database. This should result in a set of ``apache-libcloud-${VERSION}.{tar.bz2,tar.gz,zip,whl}{,asc,md5,sha1}`` files that are 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. .. sourcecode:: bash git tag For example: .. sourcecode:: bash 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.org space. 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: .. sourcecode:: bash git tag --sign v0.15.0 105b9610835f99704996d861d613c5a9a8b3f8b1 The commit SHA needs to be the one release artifacts are based on (aka the one people voted on) and the same one you used for the ``-tentative`` tag. Keep in mind that it's important that you sign the commit / tag with your GPG key. 6. Uploading release artifacts to Apache servers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Add release artifacts to the dist SVN repository at https://dist.apache.org/repos/dist/release/libcloud/ It may take up to a day for the artifacts to be available on all the Apache mirrors, but they should be instantly available at http://www.apache.org/dist/libcloud/. * If there is more than one old release in the repository, delete rest of the old release and only leave current and previous release there. Old releases are automatically archived and available at https://dist.apache.org/repos/dist/release/libcloud/. 7. Publishing package to PyPi ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We have a script that runs uploads the signed Python source files to PyPi. It uses twine, so ensure you have twine available in your path `which twine` before running. Twine can be downloaded from https://pypi.python.org/pypi/twine .. sourcecode:: bash cd dist ./deploy.sh Once all the files have been uploaded, the page should look similar to the screenshot below. .. image:: _static/images/pypi_files_page.png :width: 700px :align: center 8. Verifying the release artifact check sums ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 and makes sure that the MD5 check sums of the both files match. Usage: .. sourcecode:: bash ./dist/verify_checksums.sh For example .. sourcecode:: bash ./dist/verify_checksums.sh apache-libcloud-0.13.2 9. Updating doap_libcloud.rdf, __init__.py ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add information about the new release to the ``doap_libcloud.rdf`` file in the root of the main code repository. Update ``__version__`` attribute in ``libcloud/__init.py__`` file and indicate we are now working on a new release by incrementing a number and adding ``-dev`` suffix. For example, if version ``2.2.1`` has been released you would change it from: .. sourcecode:: python __version__ = '2.2.1' To: .. sourcecode:: python __version__ = '2.2.2-dev' 10. Updating website ~~~~~~~~~~~~~~~~~~~~ Check out the website using SVN: ``svn co https://svn.apache.org/repos/asf/libcloud/site/trunk`` * 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 ``README.md`` file. 11. Sending announcements ~~~~~~~~~~~~~~~~~~~~~~~~~ * Send a release announcement to {dev,users}@libcloud.apache.org. If it's a major 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 send information about a vulnerability to the following full disclosure mailing lists: * full-disclosure@lists.grok.org.uk * bugtraq@securityfocus.com The email you send should also be signed using your GPG key. You can find an example of such announcement on the `following url `_. If needed, use Apache URL shortening service - http://s.apache.org/ Mailing list email templates ---------------------------- This section includes email templates which can be used when sending out official communication to the mailing lists. Release voting thread template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This template should be used when starting a voting thread for a new release. Subject:: [VOTE] Release Apache Libcloud Body:: This is a voting thread for Libcloud . Full changelog can be found at . Release artifacts can be found at . KEYS file can found at https://dist.apache.org/repos/dist/release/libcloud/KEYS Please test the release and post your votes. +/- 1 [ ] Release Apache Libcloud Vote will be opened until (or longer, if needed). Thanks, For example: Subject:: [VOTE] Release Apache Libcloud 0.13.2 Body:: This is a voting thread for Libcloud 0.13.2. 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). This bug could manifest itself while uploading a file with some of the storage providers. Besides this bug fix, it includes a couple of other smaller bug fixes and changes. Full change log can be found at https://git-wip-us.apache.org/repos/asf?p=libcloud.git;a=blob;f=CHANGES;h=b7747f777afdeb63bcacf496d1d034f1b3287c31;hb=c4b3daae946049652a500a8515929b4cbf14a6b4 Release artifacts can be found at http://people.apache.org/~tomaz/libcloud/. Please test the release and post your votes. +/- 1 [ ] Release Apache Libcloud 0.13.2 Vote will be opened until September 18th, 2013 (or longer, if needed). Thanks, Tomaz Release announcement ~~~~~~~~~~~~~~~~~~~~ This template should be used when sending out a release announcement. Subject:: [ANNOUNCE] Apache Libcloud 0.13.1 release Body:: Libcloud is a Python library that abstracts away the differences among multiple cloud provider APIs. It allows users to manage cloud services (servers, storage, loadbalancers, DNS) offered by many different providers through a single, unified and easy to use API. We are pleased to announce the release of Libcloud ! Full change log can be found at Download Libcloud can be downloaded from http://libcloud.apache.org/downloads.html or installed using pip: pip install apache-libcloud Upgrading If you have installed Libcloud using pip you can also use it to upgrade it: pip install --upgrade apache-libcloud Upgrade notes A page which describes backward incompatible or semi-incompatible changes and how to preserve the old behavior when this is possible can be found at http://libcloud.apache.org/upgrade-notes.html. Documentation API documentation can be found at http://libcloud.apache.org/apidocs//. We also have a new Sphinx documentation which can be found at https://libcloud.apache.org/docs/. Bugs / Issues If you find any bug or issue, please report it on our issue tracker . Don't forget to attach an example and / or test which reproduces your problem. Thanks Thanks to everyone who contributed and made this release possible! Full list of people who contributed to this release can be found in the CHANGES file . For example: Subject:: [ANNOUNCE] Apache Libcloud 0.13.1 release Body:: Libcloud is a Python library that abstracts away the differences among multiple cloud provider APIs. It allows users to manage cloud services (servers, storage, loadbalancers, DNS) offered by many different providers through a single, unified and easy to use API. We are pleased to announce the release of Libcloud 0.13.1! This is a bug-fix only release. Among some smaller bugs it also fixes Content-Length regression which broke create and update operations in the Bluebox Compute and Azure Storage driver (LIBCLOUD-362, LIBCLOUD-3901). Full change log can be found at Download Libcloud 0.13.1 can be downloaded from http://libcloud.apache.org/downloads.html or installed using pip: pip install apache-libcloud Upgrading If you have installed Libcloud using pip you can also use it to upgrade it: pip install --upgrade apache-libcloud Upgrade notes A page which describes backward incompatible or semi-incompatible changes and how to preserve the old behavior when this is possible can be found at http://libcloud.apache.org/upgrade-notes.html. Documentation API documentation can be found at http://libcloud.apache.org/apidocs/0.13.1/. We also have a new Sphinx documentation which can be found at https://libcloud.apache.org/docs/. Keep in mind though, that this documentation reflects state in trunk which includes some backward incompatible changes which aren't present in 0.13.1. All the examples in the documentation which only work with trunk are clearly marked with a note. Bugs / Issues If you find any bug or issue, please report it on our issue tracker . Don't forget to attach an example and / or test which reproduces your problem. Thanks Thanks to everyone who contributed and made this release possible! Full list of people who contributed to this release can be found in the CHANGES file . .. _`PyPi release management page`: https://pypi.python.org/pypi?%3Aaction=pkg_edit&name=apache-libcloud