How to Contribute

If you are interested in contributing to this project, either by writing code, correcting a bug, or adding a new feature, we would love your help! Below we provide some guidelines on how to contribute.

FlowCal Installation for Developers

Regardless of your OS version, we recommend using virtualenv for development. A short primer on virtualenv can be found at http://docs.python-guide.org/en/latest/dev/virtualenvs/.

The recommended way to install FlowCal for development is to run python setup.py develop. This will install FlowCal in a special “developer” mode. In this mode, a link pointing to the FlowCal directory is made in the python installation directory, allowing you to import FlowCal from any python script, while at the same time being able to modify FlowCal’s code and immediately see the resulting effects.

Version Control

FlowCal uses git for version control. We try to follow the git-flow branching model. Please familiarize yourself with such model before contributing. A quick summary of relevant branches is given below.

  • master is only used for final release versions. Do not directly commit to master, ever.
  • develop holds unreleased features, which will eventually be released into master.
  • Feature branches are branches derived from develop, in which new features are committed. When the feature is completed, a merge request towards develop should be made.

Version Policy

The version number in FlowCal is organized as follows: MAJOR.MINOR.PATCH. The following are guidelines on how to manage version numbers:

  • The patch version number should only be increased after fixing a bug or an incompatibility issue, if the public API was not modified at all.

  • The minor version number should be increased after a relatively minor API modification. For example:

    • After fixing a bug, when a minor API modification was required to do so.
    • After making a small adjustment to a function signature, such as adding a new argument or changing the data type of an existing one.
    • After adding one or more relatively minor new features (e.g. a new plotting function).
  • The major version number should be increased after a fundamental modification to the API and/or the package, or the introduction of a major feature. For example:

    • After completely reorganizing the FCSData object or the functions in the package
    • After introducing a new Excel UI with a completely reorganized input file format.
    • After introducing a Graphical User Interface.

In general, new patch versions should not break a user’s code, whereas minor versions should not require more than minor adjustments. Major versions could either require significant changes in the user’s code or a complete change in the way they think about FlowCal’s API.