You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@libcloud.apache.org by to...@apache.org on 2013/08/05 19:10:49 UTC
[1/2] git commit: docs: Port development,
developer information and tsting page.
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 <to...@apache.org>
Authored: Mon Aug 5 16:39:31 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
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.
+
+* `users@libcloud.apache.org`_ - Mailing list for general talk about Libcloud
+ and other off-topic things
+ (`archive <https://mail-archives.apache.org/mod_mbox/libcloud-users/>`_)
+* `dev@libcloud.apache.org`_ - General mailing list for developers
+ (`archive <https://mail-archives.apache.org/mod_mbox/libcloud-dev/>`_)
+* `commits@libcloud.apache.org`_ - 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.
+
+.. _`users@libcloud.apache.org`: mailto:users-subscribe@libcloud.apache.org
+.. _`dev@libcloud.apache.org`: mailto:dev-subscribe@libcloud.apache.org
+.. _`commits@libcloud.apache.org`: mailto:commits-subscribe@libcloud.apache.org
+.. _`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.
[2/2] git commit: Update .gitignore.
Posted by to...@apache.org.
Update .gitignore.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/d53fc648
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/d53fc648
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/d53fc648
Branch: refs/heads/trunk
Commit: d53fc64801360c220d8d39fa237639eaeac0f7cc
Parents: aea0a15
Author: Tomaz Muraus <to...@apache.org>
Authored: Mon Aug 5 17:03:38 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Mon Aug 5 17:03:38 2013 +0200
----------------------------------------------------------------------
docs/.gitignore | 2 ++
1 file changed, 2 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/d53fc648/docs/.gitignore
----------------------------------------------------------------------
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..e1b2c66
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,2 @@
+_supported_providers.rst
+_supported_methods*.rst