MagnetoDB/DeveloperGuide

Setting Up a Development Environment
This page describes how to setup a working Python development environment that can be used in developing MagnetoDB on Ubuntu. These instructions assume you’re already familiar with git. Following these instructions will allow you to run the MagnetoDB unit tests. If you want to be able to run MagnetoDB, you will also need to install Cassandra and Devstack.

Virtual environments
The easiest way to build a fully functional development environment is with DevStack. Create a machine (such as a VM or Vagrant box) running a distribution supported by DevStack and install DevStack there. For example, there is a Vagrant script for DevStack at https://github.com/jogo/DevstackUp.

NOTE: If you prefer not to use devstack, you can still check out source code on your local machine and develop from there.

Linux Systems
NOTE: This section is tested for MagnetoDB on Ubuntu (12.04-64) distribution. Feel free to add notes and change according to your experiences or operating system.

Install the prerequisite packages.

Getting the code
Grab the code from GitHub:

Running unit tests
The unit tests will run by default inside a virtualenv in the .venv directory. Run the unit tests by doing:

The first time you run them, you will be asked if you want to create a virtual environment (hit “y”):

See Unit Tests for more details.

Manually installing and using the virtualenv
You can manually install the virtual environment instead of having  do it for you:

This will install all of the Python packages listed in the  file and also those listed in the   file into your virtualenv. There will also be some additional packages (pip, setuptools, greenlet) that are installed by the  file into the virutalenv.

If all goes well, you should get a message something like this:

To activate the MagnetoDB virtualenv for the extent of your current shell session you can run:

Or, if you prefer, you can run commands in the virtualenv on a case by case basis by running:

Remote development
Some modern IDE such as PyCharm (commercial/open source) support remote developing. Some useful links:

Configuring Remote Interpreters via SSH

How PyCharm helps you with remote development

Configuring to work on a VM

Also, watch this video setting up dev enviroment for cases when MagnetoDB installed on the separate machines with Devstack:

MagnetoDB dev env configuration

Contributing Your Work
Once your work is complete you may wish to contribute it to the project. Refer to Improve MagnetoDB for information. MagnetoDB uses the Gerrit code review system. For information on how to submit your branch to Gerrit, see HowToContribute.

Unit Tests
MagnetoDB contains a suite of unit tests, in the /magnetodb/tests/unittests directory.

Any proposed code change will be automatically rejected by the OpenStack Jenkins server if the change causes unit test failures.

Preferred way to run the tests
The preferred way to run the unit tests is using. See the unit testing section of the Testing wiki page for more information.

To run the Python 2.7 tests:

To run the style tests:

You can request multiple tests, separated by commas:

Older way to run the tests
Using  is preferred. It is also possible to run the unit tests using the  script found at the top level of the project. The remainder of this document is focused on.

Run the unit tests by doing:

This script is a wrapper around the testr testrunner and the flake8 checker.

Flags
The  script supports several flags. You can view a list of flags by doing:

This will show the following help information: Usage: ./run_tests.sh [OPTION]... Run MagnetoDB's test suite(s)

-V, --virtual-env       Use virtualenv. Install automatically if not present. (Default is to run tests in local environment) -F, --force             Force a clean re-build of the virtual environment. Useful when dependencies have been added. -f, --func              Functional tests have been removed. -u, --unit              Run unit tests (default when nothing specified) -p, --pep8              Run pep8 tests --all                   Run pep8 and unit tests -c, --coverage          Generate coverage report -d, --debug             Run tests with testtools instead of testr. This allows you to use the debugger. -h, --help              Print this usage message

Because  is a wrapper around testrepository, it also accepts the same flags as testr. See the testr user manual for details about these additional flags.

Running a subset of tests
Instead of running all tests, you can specify an individual directory, file, class, or method that contains test code.

To run the tests in the  directory:

To run the tests in the  file:

To run the tests in the  class in  :

To run the GetItemTestCase.test_get_item test method in :

Also note, that as all these tests (using  or  ) are run by   test runner, it is not possible to use   breakpoints in tests or the code being tested. To be able to use debugger breakpoints you should directly use  as in the following:

Virtualenv
By default, the tests use the Python packages installed inside a virtualenv. (This is equivalent to using the   flag).

If you wish to recreate the virtualenv, call   with the flag:

Recreating the virtualenv is useful if the package dependencies have changed since the virtualenv was last created. If the  or   files have changed, it’s a good idea to recreate the virtualenv.

Integration and functional tests
MagnetoDB contains a suite of integration tests (in the /magnetodb/tests/storage directory) and functional tests (in the /tempest directory).

Any proposed code change will be automatically rejected by the OpenStack Jenkins server if the change causes unit test failures.

Refer to Tests on environment with devstack for information, how to install and set enviroment and how to run such kind of tests.

Project hosting with Launchpad
Launchpad hosts the MagnetoDB project. The MagnetoDB project homepage on Launchpad is https://launchpad.net/magnetodb.

Launchpad credentials
Creating a login on Launchpad is important even if you don’t use the Launchpad site itself, since Launchpad credentials are used for logging in on several OpenStack-related sites. These sites include:
 * Wiki
 * Gerrit (see Code Reviews with Gerrit)
 * Jenkins (see Continuous Integration with Jenkins)

Mailing list
The mailing list email is. This is a common mailing list across the OpenStack projects. To participate in the mailing list:
 * 1) Subscribe at http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

The mailing list archives are at http://lists.openstack.org/pipermail/openstack-dev.

Bug tracking
Report MagnetoDB bugs at https://bugs.launchpad.net/magnetodb

Feature requests (Blueprints)
MagnetoDB uses Launchpad Blueprints to track feature requests. Blueprints are at https://blueprints.launchpad.net/magnetodb.

Technical support (Answers)
MagnetoDB uses Ask OpenStack (which are not hosted on Launchpad) to track MagnetoDB technical support questions.

Code Reviews with Gerrit
MagnetoDB uses the Gerrit tool to review proposed code changes. The review site is http://review.openstack.org.

Gerrit is a complete replacement for Github pull requests. All Github pull requests to the MagnetoDB repository will be ignored.

See How to Contribute for information about how to get started using Gerrit. See Gerrit Workflow Quick Reference and Gerrit, Jenkins and Github for more detailed documentation on how to work with Gerrit.

Also, look at Code Review Guidelines.

Continuous Integration with Jenkins
MagnetoDB uses a Jenkins server to automate development tasks. The Jenkins front-end is at http://jenkins.openstack.org. You must have an account on Launchpad to be able to access the OpenStack Jenkins site.

Jenkins performs tasks such as running static code analysis, running unit tests, and running functional tests. For more details on the jobs being run by Jenkins, see the code reviews on http://review.openstack.org. Tests are run automatically and comments are put on the reviews automatically with the results.

You can also get a view of the jobs that are currently running from the zuul status dashboard, http://status.openstack.org/zuul/.