| 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 <https://pypi.python.org/pypi/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 <https://pypi.python.org/pypi?%3Aaction=user_form>`_" 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 <https://gitbox.apache.org/setup/>`_. 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 <yourusername>@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 <version> <commit hash> |
| |
| 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 <version> |
| |
| 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 <http://seclists.org/fulldisclosure/2014/Jan/11>`_. |
| |
| 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 <version> |
| |
| Body:: |
| |
| This is a voting thread for Libcloud <version>. |
| |
| <short description and highlights of this release> |
| |
| Full changelog can be found at <link to the CHANGES file for this release>. |
| |
| Release artifacts can be found at <link to your Apache space where a release |
| artifacts can be found>. |
| |
| 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 <version> |
| |
| Vote will be opened until <date, it should be at minimum today + 3 days> (or longer, if needed). |
| |
| Thanks, |
| <name> |
| |
| 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 <version>! |
| |
| <short description of the release which should include release highlights> |
| |
| Full change log can be found at <link to CHANGES file for this release> |
| |
| Download |
| |
| Libcloud <version> 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/<version>/. |
| |
| 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 |
| <https://github.com/apache/libcloud/issues>. |
| 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 |
| <link to the changes file for this release>. |
| |
| 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 <https://git-wip-us.apache.org/repos/asf?p=libcloud.git;a=blob;f=CHANGES;h=ca90c84e296ca82e2206eb86ed7364c588aad503;hb=602b6a7a27dca6990a38eb887e1d6615826387d5> |
| |
| 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 |
| <https://github.com/apache/libcloud/issues>. |
| 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 |
| <https://git-wip-us.apache.org/repos/asf?p=libcloud.git;a=blob;f=CHANGES;h=ca90c84e296ca82e2206eb86ed7364c588aad503;hb=602b6a7a27dca6990a38eb887e1d6615826387d5>. |
| |
| .. _`PyPi release management page`: https://pypi.python.org/pypi?%3Aaction=pkg_edit&name=apache-libcloud |