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 Properties ‣ Team ‣ Advanced ‣ Assume Unchanged

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:

  1. Modify the sources in small, isolated and well-defined changes, i.e. adding a single feature, or fixing a specific bug.

  2. Add test-cases “proving” your code.

  3. 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 the setup.cfg file. Check this file for more example commands to use during development.

  4. 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.
    
  5. If there are no problems, commit your changes with a descriptive message.

  6. Repeat this cycle for further modifications.

  7. If you made a rather important modification, update also documentation (i.e. README.rst) the CHANGES and AUTHORS.

  8. 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: Travis build status (Linux), Appveyor: Apveyor build status (Windows).

3.3. Discussion