Contribute to tofu¶
You found a bug, or you want to add something to the library? This tutorial will show you how to get the repository and the first steps to contribute to the project.
Bug reports and suggestions¶
If you found a bug in tofu, or if you have a suggestion, the best is to open an issue directly on our github page. If you are opening an issue related to a bug found, please specify the version of the librairies (tofu, python, etc.) you are using, any configuration information that might be helpful to us (OS, server, how you installed tofu), a minimal example to recreate the bug (if possible), and the log files or errors you might have got.
For known bugs, scroll down to the last section.
Developping in the code¶
The basic tools¶
There are many tools and concepts to get familiar with when contributing to an open-source python library. A good place to get started is the scikit-project. And here is a list of tools you should get familiar with:
Python: the main language of tofu
IPython: powerful interactive shell for python, and check this tutorial
git, and the feature branch workflow
github: follow and watch our project
A text editor:
sublime, or whichever you want
We will use Miniconda (light version of Anaconda, but you can also work with Anaconda or another python package manager of your choice) not only to install and manage the packages necessary for installing ToFu, but also to have a working bash-like Terminal.
Follow the directions (you can use default options)
We are going to create an environment specific for ToFu.
$ conda create -n tofu3 python scipy numpy cython git ipython $ conda activate tofu3
This creates a conda environment named “tofu3” and installs scipy, numpy, git, ipython and cython. The second command activates this environment.
Create a ssh public key and add it to your GitHub account: follow this tutorial.
Go to ToFu’s GitHub repository: here.
Click on “clone or download” and swith to the option “Use SSH”. Copy the link.
Move to where you would like to install ToFu
$ cd some_path
$ git clone email@example.com:ToFuProject/tofu.git(make sure you remember the path where you are installing, if you want to install it into your home repository, just make sure to
cd ~before the
Move to the tofu directory, probably:
Switch to the
gitbranch you will be working on. If you are just starting you probably want to start from the latest develop branch:
git checkout devel. If you are not familiar with git take a look at this tutorial (long) or this short one
python setup.py build_ext --inplace
Make sure tests are running
Where to start?¶
Git branches and pull requests¶
Before modifying the code, you should create a new branch (based on the devel branch) and switch to it.
git checkout -b <theNameOfYourBranch> # probably IssueNumber eg. Issue123 # change the source code git add <files you changed> git commit -m "[a tag] a message that explains what you changed" git push -u origin <theNameOfYourBranch>
Now you can open a pull request in our github
page, from your branch,
devel. We will review it, comment it, and
For each pull request (PR) on github, there will be a series of tests run to make sure the modifications introduced to the library did not introduce any errors. If all tests pass, you should see something like the image below.
If there is an error (red cross instead of green check) it can be either that your code is breaking the normal functionning of the code, or (less probably) that there is a bug in the unit tests. Please try and understand what went wrong. If you cannot find the problem, you can ask for help by commenting on the PR. Additionally to the unit tests, we have integrated pep8speaks, a bot that will check your coding style.
numpy.ndarayy size changed¶
NumPy 1.20 introduced a different ABI (application binary interface, basically changing the binary size of its objects), Cython librairies compiled with older version but using this new version for building its wheels, will encounter the error below:
ValueError: numpy.ndarray size changed, may indicate binary incompatibility. Expected 88 from C header, got 80 from PyObject
So we recommend using the latest version of
NumPy (>= 1.20).
If that’s not possible for whatever reasons, there are still some workarounds
you can try (see this post for example).
The one that has worked best for us is using the following line
pip install tofu --no-build-isolation --no-cache-dir --no-binary :all:
If you still encounter this issue, if you have questions, or want to suggests other solutions, you can comment in the issue opened on github for this matter: here.