Skip to content

CONTRIBUTING.md draft

Jump to bottom
Samuel Farrens edited this page May 14, 2019 · 16 revisions

Contributing to pySAP

pySAP is a Python module for sparse data analysis that offers:

  • a common API for astronomical and neuroimaging datasets,
  • accces to Sparse2d using a wrappers and bindings,
  • and a user graphical interface to play with the provided functions.

This package has been developed in collaboration between CosmoStat and NeuroSpin via the COSMIC project.

Contents

  1. Introduction
  2. Architecture
  3. Issues
    1. Asking Questions
    2. Installation Issues
    3. Reporting Bugs
    4. Requesting Features
    5. Requesting Plugin Integration
  4. Pull Requests
    1. Before Making a PR
    2. Making a PR
    3. After Making a PR
    4. Content
    5. CI Tests
    6. Coverage
    7. Style Guide
  5. Plugins
    1. Available Plugins
    2. Developing a New Plugin
  6. Examples
    1. Example Content
    2. Example Style
    3. Example Data

Introduction

pySAP is fully open-source and as such users are welcome to fork, clone and/or reuse the software freely. Users wishing to contribute to the development of this package, however, are kindly requested to adhere to the following guidelines and the code of conduct.

Architecture

For the end user PySAP is meant to function as an all-in-one tool for image analysis, however the package itself is comprised of various independently managed repositories. Potential developers should be aware of where and how to contribute to each of these components.

  • PySAP: The core repository is primarily responsible for the user interface and the bindings/wrappers for Sparse2D.
  • ModOpt: This package handles all of the optimisation algorithms and corresponding tools needed to solve linear inverse problems.
  • Sparse2D: This package provides C++ libraries for implementing 1D, 2D and 3D wavelet decompositions of images.
  • Plugins: Plugins combine PySAP modules to provide application specific tools for various image analysis problems.

Issues

The easiest way to contribute to pySAP is by raising a "New issue". This will give you the opportunity to ask questions, report bugs or even request new features.

Whenever possible, issues should be raised using one of the available templates. This will help other users that encounter similar problems find quick solutions. We also ask that you read the available documentation and browse existing issues on similar topics before raising a new issue in order to avoid repetition.

Asking Questions

Users are of course welcome to ask any question relating to pySAP and we will endeavour to reply as soon as possible.

These issues should raised using the "Help!" template.

Installation Issues

If you encounter difficulties installing pySAP be sure to re-read the installation instructions provided. If you are still unable to install the package please remember to include the following details in the issue you raise:

  • your operating system and the corresponding version (e.g. macOS v10.14.1, Ubuntu v16.04.1, etc.),
  • the version of Python you are using (e.g v2.7.14, v3.6.7, etc.),
  • the python environment you are using (if any) and the corresponding version (e.g. virtualenv v16.1.0, conda v4.5.11, etc.),
  • the C compiler you are using and the corresponding version (e.g. gcc v7.2.0),
  • the CMake version you are using (e.g. 3.12.0),
  • the exact steps followed while attempting to install pySAP
  • and the error message printed or a screen capture of the terminal output.

These issues should raised using the "Installation issue" template.

Reporting Bugs

If you discover a bug while using pySAP please provide the same information requested for installation issues. Be sure to list the exact steps you followed that lead to the bug you encountered so that we can attempt to recreate the conditions.

If you are aware of the source of the bug we would very much appreciate if you could provide the module(s) and line number(s) affected. This will enable us to more rapidly fix the problem.

These issues should raised using the "Bug report" template.

Requesting Features

If you believe pySAP could be improved with the addition of extra functionality or features feel free to let us know. We cannot guarantee that we will include these features, but we will certainly take your suggestions into consideration.

In order to increase your chances of having a feature included, be sure to be as clear and specific as possible as to the properties this feature should have.

These issues should raised using the "Feature request" template.

Requesting Plugin Integration

If you have developed a new PySAP plugin you can request that it be formally integrated into the package by opening an issue. Be sure to provide a link the repository where the plugin has been developed and explain the purpose of the plugin. Your request will then be reviewed and if accepted instructions will be provided on how to proceed.

These issues should raised using the "Plugin review" template.

Pull Requests

If you would like to take a more active roll in the development of pySAP you can do so by submitting a "Pull request". A Pull Requests (PR) is a way by which a user can submit modifications or additions to the pySAP package directly. PRs need to be reviewed by the package moderators and if accepted are merged into the master branch of the repository.

Before making a PR, be sure to carefully read the following guidelines.

Before Making a PR

The following steps should be followed before making a pull request:

  1. Identify the correct repository for submitting the PR. When in doubt, raise an issue.

    • PR concerning interface or bindings → PySAP
    • PR concerning optimisation algorithms → ModOpt
    • PR concerning wavelet transforms → Sparse2D
    • PR concerning a specific application → CEA-COSMIC/pysap-PLUGIN

  2. Log into your GitHub account or create an account if you do not already have one.

  3. Go to the relevant repository page: e.g. https://github.com/CEA-COSMIC/pysap

  4. Fork the repository, i.e. press the button on the top right with this symbol . This will create an independent copy of the repository on your account.

  5. Clone your fork of the repository. e.g.

  git clone https://github.com/YOUR_USERNAME/pysap
  1. Add the original repository (upstream) to remote. e.g. 
  git remote add upstream https://github.com/CEA-COSMIC/pysap

Making a PR

The following steps should be followed to make a pull request:

  1. Pull the latest updates to the original repository.
  git pull upstream master
  1. Create a new branch for your modifications.
  git checkout -b BRANCH_NAME

  1. Make the desired modifications to the relevant modules.

  2. Add the modified files to the staging area.

  git add .
  1. Make sure all of the appropriate files have been staged. Note that all files listed in green will be included in the following commit.
  git status
  1. Commit the changes with an appropriate description.
  git commit -m "Description of commit"
  1. Push the commits to a branch on your fork of pySAP.
  git push origin BRANCH_NAME

  1. Make a pull request for your branch with a clear description of what has been done, why and what issues this relates to.

  2. Wait for feedback and repeat steps 3 through 7 if necessary.

After Making a PR

If your PR is accepted and merged it is recommended that the following steps be followed to keep your fork up to date.

  1. Make sure you switch back to your local master branch.
  git checkout master
  1. Delete the local branch you used for the PR.
  git branch -d BRANCH_NAME
  1. Pull the latest updates to the original repository, which include your PR changes.
  git pull upstream master
  1. Push the commits to your fork.
  git push origin master

Content

Every PR should correspond to a bug fix or new feature issue that has already be raised. When you make a PR be sure to tag the issue that it resolves (e.g. this PR relates to issue #1). This way the issue can be closed once the PR has been merged.

The content of a given PR should be as concise as possible. To that end, aim to restrict modifications to those needed to resolve a single issue. Additional bug fixes or features should be made as separate PRs.

CI Tests

Continuous Integration (CI) tests are implemented via Travis CI. All PRs must pass the CI tests before being merged. Your PR may not be reviewed by a moderator until all CI test are passed. Therefore, try to resolve any issues in your PR that may cause the tests to fail.

In some cases it may be necessary to modify the unit tests, but this should be clearly justified in the PR description.

Coverage

Coverage tests are implemented via Coveralls. These tests will fail if the coverage, i.e. the number of lines of code covered by unit tests, decreases. When submitting new code in a PR, contributors should aim to write appropriate unit tests. If the coverage drops significantly moderators may request unit tests be added before the PR is merged.

Style Guide

All contributions should adhere to the following style guides currently implemented in pySAP:

  1. All code should be compatible with the Python versions listed in README.rst. At present this requires backwards compatibility with Python 2.7.

  2. All code should adhere to PEP8 standards.

  3. Docstrings need to be provided for all new modules, methods and classes. These should adhere to numpydoc standards.

  4. When in doubt look at the existing code for inspiration.

Plugins

Available Plugins

At present the following plugins are available:

  • PySAP-astro: Plugin for astrophysical data.
  • PySAP-mri: Plugin for magnetic resonance imaging data.

Developing a New Plugin

If you have found a new application for PySAP you may wish to develop a new plugin. To do so you should adhere to the following steps:

  1. Fork the plugin template: https://github.com/CEA-COSMIC/pysap-extplugin
  2. Rename the template to reflect the content of your plugin and add the features you want.
  3. Test your plugin locally with PySAP. You should be able to access your plugin as follows.
import pysap.plugins.PLUGIN-NAME
  1. Finally, open an issue on the PySAP repository requesting that your plugin be formally integrated.

Examples

Example Content

Examples should contain...

Examples should not contain...

Example Style

Examples should respect the same style conventions used in the core pySAP code (see Style Guide). Please refer to the Example Template for instructions on how to properly structure your example.

Example Data

Data sets required for running pySAP examples should be stored...

Clone this wiki locally