3. Getting Involved¶
This project is hosted in github. To provide feedback about bugs and errors or questions and requests for enhancements, use github’s Issue-tracker.
3.1. Sources & Dependencies¶
To get involved with development, you need a POSIX environment to fully build it (Linux, OSX or Cygwin on Windows).
First you need to download the latest sources:
$ git clone https://github.com/pandalone/pandalone.git pandalone.git
$ cd pandalone.git
Virtualenv
You may choose to work in a virtualenv (isolated Python environment), to install dependency libraries isolated from system’s ones, and/or without admin-rights (this is recommended for Linux/Mac OS).
Attention
If you decide to reuse stystem-installed packages using option --system-site-packages
with virtualenv <= 1.11.6
(to avoid, for instance, having to reinstall numpy and pandas that require native-libraries)
you may be bitten by bug #461 which
prevents you from upgrading any of the pre-installed packages with pip.
Liclipse IDE
Within the sources there are two sample files for the comprehensive LiClipse IDE:
eclipse.project
eclipse.pydevproject
Remove the eclipse
prefix, (but leave the dot()) and import it as “existing project” from
Eclipse’s
File
menu.
Another issue is caused due to the fact that LiClipse contains its own implementation of Git, EGit,
which badly interacts with unix symbolic-links, such as the docs/docs
, and it detects
working-directory changes even after a fresh checkout. To workaround this, Right-click on the above file
Then you can install all project’s dependencies in `development mode using the setup.py
script:
$ python setup.py --help ## Get help for this script.
Common commands: (see '--help-commands' for more)
setup.py build will build the package underneath 'build/'
setup.py install will install the package
Global options:
--verbose (-v) run verbosely (default)
--quiet (-q) run quietly (turns verbosity off)
--dry-run (-n) don't actually do anything
...
$ python setup.py develop ## Also installs dependencies into project's folder.
$ python setup.py build ## Check that the project indeed builds ok.
You should now run the test-cases to check that the sources are in good shape:
$ python setup.py test
Note
The above commands installed the dependencies inside the project folder and
for the virtual-environment. That is why all build and testing actions have to go through
python setup.py some_cmd
.
If you are dealing with installation problems and/or you want to permantly install dependant packages, you have to deactivate the virtual-environment and start installing them into your base python environment:
$ deactivate
$ python setup.py develop
or even try the more permanent installation-mode:
$ python setup.py install # May require admin-rights
3.2. Design¶
See architecture live-document.
For submitting code, use UTF-8
everywhere, unix-eol(LF
) and
set git --config core.autocrlf = input
.
The typical development procedure is like this:
Modify the sources in small, isolated and well-defined changes, i.e. adding a single feature, or fixing a specific bug.
Add test-cases “proving” your code.
Rerun all test-cases to ensure that you didn’t break anything, and check their coverage remain above 80%:
$ python setup.py test_code_cover
Tip
You can enter just:
python setup.py test_all
instead of the above cmd-line since it has been aliased in thesetup.cfg
file. Check this file for more example commands to use during development.To see the rendered results of the documents, issue the following commands and read the result html at
build/sphinx/html/index.html
:$ python setup.py build_sphinx # Builds html docs $ python setup.py build_sphinx -b doctest # Checks if python-code embeded in comments runs ok.
If there are no problems, commit your changes with a descriptive message.
Repeat this cycle for further modifications.
If you made a rather important modification, update also documentation (i.e. README.rst) the
CHANGES
andAUTHORS
.When you are finished, push the changes upstream to github and make a merge_request. You can check whether your merge-request indeed passed the tests by checking its build-status, on both integration site: Travis: , Appveyor: .
Hint
Skim through these small guides: