Contributing to Poromics

Poromics is a collection of tools to rapidly estimate transport properties of 2D/3D images of porous materials. We use Poromics regularly in our research, and we hope you will too. The package is open-source, and we welcome contributions from the community. This document describes how to get involved.

Before you start you'll need to set up a free GitHub account and sign in. Here are some instructions to get started.

Ways to Contribute

Open a New Issue

We use Github to track issues. Issues can take the form of:

(a) bug reports such as a function producing an error or odd result in some circumstances.

(b) feature requests such a suggesting a new function be added to the package, presumably based on some literature report that describes it, or enhancements to an existing function.

(c) general usage questions where the documentation is not clear and you need help getting a function to work as desired. This is actually a bug report in disguise since it means there is a problem with the documentation.

Addressing Open Issues

Help fixing open issues is always welcome; however, the learning curve for submitting new code to any repo on Github is a bit intimidating. The process is as follows:

a) Fork Poromics to your own Github account. This lets you work on the code since you are the owner of that forked copy.

b) Pull the code to your local machine using some Git client. We suggest GitKraken. For help using the Git version control system, see these resources.

c) Create a new branch, with a useful name like "fix_issue_41" or "add_awesome_solver", then checkout that branch.

d) Edit the code as desired, either fixing or adding something. You'll need to know Python and the various packages in the SciPy stack for this part.

e) Push the changes back to Github, to your own repo.

f) Navigate to the pull requests area on the Poromics repo, then click the "new pull request" button. As the name suggests, you are requesting us to pull your code in to our repo. You'll want to select the correct branch on your repo (e.g. "add_awesome_filter") and the "dev" branch on Poromics.

g) This will trigger several things on our repo, including most importantly a conversation between you and the Poromics team about your code. After any fine-tuning is done, we will merge your code into Poromics, and your contribution will be immortalized in Poromics.

Note

Adapted from PoreSpy's contributing guide.