Updated Branches: refs/heads/trunk a06cd308c -> d53fc6480
docs: Port development, developer information and tsting page. Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/aea0a15b Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/aea0a15b Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/aea0a15b Branch: refs/heads/trunk Commit: aea0a15bfda158d4b06102324b482a7dcbaa236e Parents: a06cd30 Author: Tomaz Muraus <[email protected]> Authored: Mon Aug 5 16:39:31 2013 +0200 Committer: Tomaz Muraus <[email protected]> Committed: Mon Aug 5 17:02:50 2013 +0200 ---------------------------------------------------------------------- docs/developer_information.rst | 52 +++++++++++++++ docs/development.rst | 123 ++++++++++++++++++++++++++++++++++++ docs/testing.rst | 77 ++++++++++++++++++++++ 3 files changed, 252 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/aea0a15b/docs/developer_information.rst ---------------------------------------------------------------------- diff --git a/docs/developer_information.rst b/docs/developer_information.rst new file mode 100644 index 0000000..1f8337f --- /dev/null +++ b/docs/developer_information.rst @@ -0,0 +1,52 @@ +Developer Information +===================== + +Mailing Lists +------------- + +All of the communication about Libcloud development happens on our mailing +lists. + +* `[email protected]`_ - Mailing list for general talk about Libcloud + and other off-topic things + (`archive <https://mail-archives.apache.org/mod_mbox/libcloud-users/>`_) +* `[email protected]`_ - General mailing list for developers + (`archive <https://mail-archives.apache.org/mod_mbox/libcloud-dev/>`_) +* `[email protected]`_ - Commits messages go to this mailing list. + Keep ind mind that unlike the others, this mailing list is fairly noisy. + (`archive <https://mail-archives.apache.org/mod_mbox/libcloud-commits/>`_) + +Archive of old incubator mailing lists: + +* `incubator-libcloud`_ +* `incubator-libcloud-commits`_ + +Issue Tracker +------------- + +For bug and issue tracking we use JIRA located at +https://issues.apache.org/jira/browse/LIBCLOUD. + +Testing +------- + +For information how to run the tests and how to generate the test coverage +report, please see the :doc:`Testing page </testing>`. + +Continuous Integration +---------------------- + +For continuous integration we use buildbot. You can find all the build reports +`here <https://ci.apache.org/waterfall?builder=libcloud-trunk-tox&builder=libcloud-site-staging>`_. + +Test Coverage +------------- + +Test coverage report is automatically generated after every push and can be +found at http://ci.apache.org/projects/libcloud/coverage. + +.. _`[email protected]`: mailto:[email protected] +.. _`[email protected]`: mailto:[email protected] +.. _`[email protected]`: mailto:[email protected] +.. _`incubator-libcloud`: http://mail-archives.apache.org/mod_mbox/incubator-libcloud/ +.. _`incubator-libcloud-commits`: http://mail-archives.apache.org/mod_mbox/incubator-libcloud-commits/ http://git-wip-us.apache.org/repos/asf/libcloud/blob/aea0a15b/docs/development.rst ---------------------------------------------------------------------- diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 0000000..40d7fe4 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,123 @@ +Development +=========== + +Contributing +------------ + +We welcome contributions of any kind (ideas, code, tests, documentation, +examples, ...). + +This page explains how you can contribute to the Libcloud project. If you get +stuck at any point during this process, stop by on our IRC channel (#libcloud +on freenode) and we will do our best to assist you. + +Style Guide +----------- + +* We follow `PEP8 Python Style Guide`_ +* Use 4 spaces for a tab +* Make sure edited file doesn't contain any trailing whitespace +* You can verify that your modifications don't break any rules by running the + ``pep8 script - e.g. pep8 libcloud/edited_file.py.`` + +General guidelines +------------------ + +* Any non-trivial change must contain tests +* All the functions and methods must contain Sphinx docstrings which are used + to generate API documentation. You can find a lot of examples of docstrings + in the existing code e.g. - ``libcloud/compute/base.py`` +* If you are adding a new feature, make sure to add corresponding documentation + +Contribution workflow +--------------------- + +1. If you are implementing a big feature or a change, start a discussion on the + mailing list first. +2. Open a new issue on our `issue tracker`_ (JIRA) +3. Fork libcloud `Github git repository`_ and make your changes +4. Create a new branch for your changes: + ``git checkout -b <jira_issue_id>_<change_name>`` +5. Make your changes +6. Make a single commit for your changes and if a corresponding JIRA + ticket exists, make sure the commit message contains the ticket number. + For example: ``git commit -a -m "Issue LIBCLOUD-123: Add a new compute driver for CloudStack based providers."`` +7. Write tests for your modifications and make sure that all the tests pass. + For more information about running the tests refer to the Testing page. +8. Open a pull request with your changes. Your pull request will appear at + https://github.com/apache/libcloud/pulls +9. Wait for the code to be reviewed and address any outstanding comments. +10. Once the code has been reviewed, all the outstanding issues have been + addressed and the pull request has been +1'ed, close the pull request, + generate a patch and attach it to the JIRA issue you have created earlier: + ``git format-patch --stdout trunk > patch_name.patch`` + +Note about Github +~~~~~~~~~~~~~~~~~ + +Github repository is a read-only mirror of the official Apache git repository +(``https://git-wip-us.apache.org/repos/asf/libcloud.git``). This mirror script +runs only a couple of times per day which means this mirror can be slightly out +of date. + +You are advised to add a separate remote for the official upstream repository: + +.. sourcecode:: bash + git remote add upstream https://git-wip-us.apache.org/repos/asf/libcloud.git + +Github read-only mirror is used only for pull requests and code review. Once a +pull request has been reviewed, all the comments have been addresses and it's +ready to be merged, user who submitted the pull request must close the pull +request, create a patch and attach it to the original JIRA ticket. + +Contributing Bigger Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you are contributing a bigger change (e.g. large new feature or a new +provider driver) you need to have have signed Apache Individual Contributor +License Agreement (ICLA) in order to have your patch accepted. + +You can find more information on how to sign and file an ICLA on the +`Apache website`_. + +Supporting Multiple Python Versions +----------------------------------- + +Libcloud supports a variety of Python versions so your code also needs to work +with all the supported versions. This means that in some cases you will need to +include extra code to make sure it works in all the supported versions. Some +examples are included bellow. + +Context Managers +~~~~~~~~~~~~~~~~ + +Context managers aren't available in Python 2.5 by default. If you want to use +them make sure to put from ``__future__ import with_statement`` on top of the +file where you use them. + +Exception Handling +~~~~~~~~~~~~~~~~~~ + +There is no unified way to handle exceptions and extract the exception object +in Python 2.5 and Python 3.x. This means you need to use a +``sys.exc_info()[1]`` approach to extract the raised exception object. + +For example: + +.. sourcecode:: python + + try: + some code + except Exception: + e = sys.exc_info()[1] + print e + +Python 3 +~~~~~~~~ + +You can find a lot of utility functions which make code easier to work with +2.x and 3.x in ``libcloud.utils.py3`` module. + +.. _`PEP8 Python Style Guide`: http://www.python.org/dev/peps/pep-0008/ +.. _`Issue tracker`: https://issues.apache.org/jira/browse/LIBCLOUD +.. _`Github git repository`: https://github.com/apache/libcloud +.. _`Apache website`: https://www.apache.org/licenses/#clas http://git-wip-us.apache.org/repos/asf/libcloud/blob/aea0a15b/docs/testing.rst ---------------------------------------------------------------------- diff --git a/docs/testing.rst b/docs/testing.rst new file mode 100644 index 0000000..335c1c7 --- /dev/null +++ b/docs/testing.rst @@ -0,0 +1,77 @@ +Testing +======= + +Prerequisites +------------- + +.. note:: + + If you use the tox method described bellow you don't need to install any + dependencies, because tox automatically installs them for you in an virtual + environment. + +To run the libcloud test suite you need to have the following extra +dependencies installed: + +* ``tox`` (``pip install tox``) - you only need this library if you want to + use tox to run the tests with all the supported Python versions +* ``mock`` (``pip install mock``) +* ``lockfile`` (``pip install lockfile``) - only used in the local storage + storage driver +* ``coverage`` (``pip install coverage``) - you only need this library if you + want to generate a test coverage report + + +Running Tests On All the Supported Python Versions Using tox +------------------------------------------------------------ + +.. note:: + tox uses virtualenv and won't pollute your local Python installation. + +To run the tests on all the supported Python versions run the following command: + +.. sourcecode:: bash + + sudo tox + +You need to run this command as a root user, because Python 2.5 depends on ssl +module and you need root permissions to install it. + +Running Tests Manually +---------------------- + +To run the tests manually, you first need to install all of the dependencies +mentioned above. After that simply go to the root of the repository and use the +following command: + +.. sourcecode:: bash + + PYTHONPATH=. python setup.py test + +Running a Single Test File +-------------------------- + +To run the tests located in a single test file, move to the root of the +repository and run the following command: + +.. sourcecode:: bash + + PYTHONPATH=. python libcloud/test/<path to test file> + +For example: + +.. sourcecode:: bash + + PYTHONPATH=. python libcloud/test/libcloud/test/compute/test_ec2.py + +Generating Test Coverage Report +------------------------------- + +To generate the test coverage run the following command: + +.. sourcecode:: bash + + PYTHONPATH=. python setup.py coverage + +When it completes you should see a new ``coverage_html_report`` directory which +contains the test coverage.
