PyWBEM Client - Contributing
The PyWBEM Client project has its repository at https://github.com/pywbem/pywbem.
The maintainers all have day jobs, so its development is really a community effort. Contributions are always welcome!
If you want to contribute, you can do that in a number of areas:
- Testing on new platforms (operating systems, Python implementations and versions)
- Extending the unit test cases
- Reporting bugs you encounter, on the issue tracker
- Fixing bugs or implementing feature requests listed on the issue tracker
- Doing things listed on the ToDo list
This section provides some hints when you want to participate in the development of the PyWBEM Client. You can ignore it when you just want to use the PyWBEM Client and program against it.
First, create a local clone of the PyWBEM Git repository:
git clone email@example.com:pywbem/pywbem.git cd pywbem
It is strongly recommended to use a virtual Python environment for each version of Python supported by PyWBEM:
mkvirtualenv -p python2.6 pywbem26 mkvirtualenv -p python2.7 pywbem27
As of the PyWBEM Client v0.8, its setup script (setup.py) establishes any Python prerequisites for its own development when invoked with the "develop" command. This needs to be done in each of the virtual Python environments that were set up for PyWBEM (do not use sudo, otherwise it will install into the system Python):
cd src workon pywbem26 python setup.py develop workon pywbem27 python setup.py develop
In addition, the setup script establishes any OS-level prerequisites for its own development when invoked with the "develop_os" command:
sudo python setup.py develop_os
The PyWBEM Client also provides a makefile. Invoking make without arguments will print the possible targets:
make makefile for pywbem Package version will be: 0.8.1 Uses the currently active Python environment: Python 27 Valid targets are (they do just what is stated, i.e. no automatic prereq targets): develop - Prepare the development environment by installing prerequisites build - Build the distribution archive: dist/pywbem-0.8/pywbem-0.8.1.tar.gz buildwin - Build the Windows installable: dist/pywbem-0.8/pywbem-0.8.1.win-amd64.exe (requires Windows 64-bit) builddoc - Build documentation in: build_doc check - Run PyLint on sources and save results in: pylint.log install - Install distribution archive to active Python environment test - Run unit tests and save results in: test_27.log clean - Remove any temporary files; ensure clean build start all - Do everything locally (except publish/upload) upload - build + upload the distribution archive to PyPI: dist/pywbem-0.8/pywbem-0.8.1.tar.gz publish - builddoc + publish documentation to: ../pywbem.github.io/pywbem/doc/0.8.1/doc clobber - Remove any build products
The PyWBEM Client has some amount of unit test cases. Invoke make test to build and install the PyWBEM Client and to run the unit test cases on the current operating system and the current Python environment.
Any help in completing the unit test cases is very welcome. If you feel like helping, search for occurrences of TODO in the Python source files in directory src/testsuite.
The following table lists the environments in which the installation and the unit test cases are tested. The responsible person for a row should open issues if any tests are failing.
|OS Type||OS Name||OS Version||HW platform||Python Version||Responsible||Remarks|
|Linux||Arch||(latest)||i386, x86_64||2.7||Andreas Maier||Under construction|
|Linux||CentOS||6.7||i386, x86_64||2.6, 2.7||Andreas Maier||Under construction|
|Linux||CentOS||7||x86_64||2.6, 2.7||Andreas Maier||Under construction|
|Linux||Debian||8.2||i386, x86_64||2.7||Andreas Maier||Under construction|
|Linux||Fedora||20||x86_64||2.7||Andreas Maier||Under construction|
|Linux||Fedora||22||i386||2.7||Andreas Maier||Under construction|
|Linux||openSUSE||42||i386, x86_64||2.7||Andreas Maier||Under construction|
|Linux||Ubuntu||12.04||x86_64||2.6, 2.7||Andreas Maier||Results on Travis CI|
|Linux||Ubuntu||14.04||i386, x86_64||2.7||Andreas Maier||Under construction|
|Windows||Windows||7||x86_64||2.6, 2.7||Andreas Maier||Under construction|
The number of committers in the PyWBEM Client project is small and should stay small. If you are not a committer but want to submit code, you have two choices:
Pull request (preferred):
Create a fork of the PyWBEM Client project (anywhere you have a public Git server, but there are some advantages doing that on GitHub), develop and commit your changes there, and once you are done, create a pull request targeting the PyWBEM Client project on GitHub (https://github.com/pywbem/pywbem).
It is helpful if the pull request is related to an issue in the PyWBEM Client issue tracker.
A good description on how to use git on GitHub forks, can be found in the GitHub Guide: Forking Projects.
Work in your local Git clone, and once you are done, create a patch file reflecting your changes. Attach the patch file to an issue in the issue tracker. The commit level in the PyWBEM Client project on GitHub for which the patch file is intended should be indicated somehow.
As a PyWBEM developer, you may work on the development environment and not everything may work right all the time. Here is a list of things that have gone wrong in the past, and how to resolve them.
These issues should not occur for users of PyWBEM, because the PyWBEM setup script (setup.py) takes care of them.
Error when installing M2Crypto (e.g. as part of installing the PyWBEM Client):
unable to execute swig: No such file or directory
Root cause: This error occurs when M2Crypto is installed as part of the PyWBEM Client installation, and the swig command is not available.
Solution: Install Swig (Linux: package swig). The M2Crypto installation requires at least Swig version 2.0. If your operating system does not provide for such a version, download and build Swig 2.0. Note that this is done automatically by the "develop" and "install" commands of the setup script of the PyWBEM Client.
Error when installing M2Crypto (e.g. as part of installing PyWBEM):
swig error : Unrecognized option -builtin
Root cause: This error occurs when M2Crypto is installed as part of the PyWBEM Client installation, and the version of swig is not sufficient. The M2Crypto installation requires at least Swig version 2.0.
Solution: Update your version of Swig to at least 2.0. If your operating system does not provide for such a version, download and build Swig 2.0. Note that this is done automatically by the "develop_os" and "install_os" commands of the setup script of the PyWBEM Client.
Error when building Swig:
configure: error: Cannot find pcre-config script from PCRE (Perl Compatible Regular Expressions) library package.
Root cause: The PCRE development package is not installed.
Solution: Install the PCRE development package:
sudo yum install pcre-devel # if RedHat-based sudo apt-get install pcre-devel # if Debian-based sudo zypper install pcre-devel # if SUSE-based
Error when installing M2Crypto (e.g. as part of installing PyWBEM):
SWIG/_m2crypto.i:31: Error: Unable to find 'openssl/opensslv.h'
SWIG/_m2crypto.i:45: Error: Unable to find 'openssl/safestack.h'
SWIG/_evp.i:12: Error: Unable to find 'openssl/opensslconf.h'
SWIG/_ec.i:7: Error: Unable to find 'openssl/opensslconf.h'
Root cause: The OpenSSL development package is not installed.
Solution: Install the OpenSSL development package:
sudo yum install openssl-devel # if RedHat-based sudo apt-get install libssl-devel # if Debian-based sudo zypper install openssl-devel # if SUSE-based
Note that installing the PyWBEM Client to the system Python invokes the M2Crypto build also under root permissions, so the new Swig version needs to be available via the PATH of root, in this case.
Verify that the new version is available both for your userid and for root:
swig -version sudo swig -version