Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions¶
Report bugs at https://github.com/akrog/cinderlib/issues.
If you are reporting a bug, please include:
- Your operating system name and version.
- Storage backend and configuration used (replacing sensitive information with asterisks).
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.
Look through the GitHub issues and the TODO file for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.
We currently lack decent test coverage, so feel free to look into our existing tests to add missing tests, because any test that increases our coverage is more than welcome.
Cinder Library could always use more documentation, whether as part of the official Cinder Library docs, in docstrings, or even on the web in blog posts, articles, and such.
The best way to send feedback is to file an issue at https://github.com/akrog/cinderlib/issues.
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions are welcome :)
Ready to contribute? Here’s how to set up cinderlib for local development.
- Fork the cinderlib repo on GitHub.
- Clone your fork locally:
$ git clone email@example.com:YOUR_NAME_HERE/cinderlib.git
- Install tox:
$ sudo dnf install python2-tox
- Generate a virtual environment, for example for Python 2.7:
$ tox --notest -epy27
- Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally.
- When you’re done making changes, you can check that your changes pass flake8 and unit tests with:
$ tox -eflake8 $ tox -epy27 Or if you don't want to create a specific environment for flake8 you can run things directly without tox:
$ source .tox/py27/bin/activate $ flake8 cinderlib tests $ python setup.py test
- Run functional tests at least with the default LVM configuration:
$ tox -efunctional To run the LVM functional tests you'll need to have the expected LVM VG ready. This can be done using the script we have for this purpose (assuming we are in the *cinderlib* base directory):
$ mkdir temp $ cd temp $ sudo ../tools/lvm-prepare.sh The default configuration for the functional tests can be found in the `tests/functional/lvm.yaml` file. For additional information on this file format and running functional tests please refer to the :doc:`validating_backends` section. And preferably with all the backends you have at your disposal:
$ CL_FTESTS_CFG=temp/my-test-config.yaml tox -efunctional
Commit your changes making sure the commit message is descriptive enough, covering the patch changes as well as why the patch might be necessary. The commit message should also conform to the 50/72 rule.
$ git add . $ git commit
Push your branch to GitHub:
$ git push origin name-of-your-bugfix-or-feature
- Submit a pull request through the GitHub website.
You may not have a fancy storage array, but that doesn’t mean that you cannot use cinderlib, because you can always the LVM driver. Here we are going to see how to setup an LVM backend that we can use with cinderlib.
Before doing anything you need to make sure you have the required package, for Fedora, CentOS, and RHEL this will be the targetcli package, and for Ubuntu the lio-utils package.
$ sudo yum install targetcli
Then we’ll need to create your “storage backend”, which is actually just a file on your normal filesystem. We’ll create a 22GB file with only 1MB currently allocated (this is worse for performance, but better for space), and then we’ll mount it as a loopback device and create a PV and VG on the loopback device.
$ dd if=/dev/zero of=temp/cinder-volumes bs=1048576 seek=22527 count=1 $ sudo lodevice=`losetup --show -f ./cinder-volumes` $ sudo pvcreate $lodevice $ sudo vgcreate cinder-volumes $lodevice $ sudo vgscan --cache
There is a script included in the repository that will do all this for us, so we can just call it from the location where we want to create the file:
$ sudo tools/lvm-prepare.sh
Now we can use this LVM backend in cinderlib:
import cinderlib as cl from pprint import pprint as pp lvm = cl.Backend(volume_driver='cinder.volume.drivers.lvm.LVMVolumeDriver', volume_group='cinder-volumes', target_protocol='iscsi', target_helper='lioadm', volume_backend_name='lvm_iscsi') vol = lvm.create_volume(size=1) attach = vol.attach() pp('Volume %s attached to %s' % (vol.id, attach.path)) vol.detach() vol.delete()
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
- The pull request should include tests.
- If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
- The pull request should work for Python 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check https://travis-ci.org/akrog/cinderlib/pull_requests and make sure that the tests pass for all supported Python versions.
To run a subset of tests:
$ source .tox/py27/bin/activate $ python -m unittest tests.test_cinderlib.TestCinderlib.test_lib_setup