Contributing

If you are reading this, first of all, thank you and welcome to this community. For everyone to have fun, every good python projects requires some guidelines to be observed.

Every code seek to be performant, usable, stable and maintainable. This can only be acheave through high test coverage, good documentation and coding consistency. Isn’t it frustrating when you cannot understand some code just because there is no documentation nor any test to assess that the function is working nor any comments in the code itself? How are you supposed to code in these conditions?

If you wish to contribute, you must comply to the following rules for your pull request to be considered.

Install

The procedure is similar to the end-user one but if you plan to modify the sources, you need to install it with:

python setup.py develop

This will create a simlink to your python install folder. Thus you won’t have to re-install the package after you modified it.

Make sure you have installed the testing dependencies as detailed in the README.

Python

This is a python project, not some C or Fortran code. You have to adapt your thinking to the python style. Otherwise, this can lead to performance issues. For example, an if is expensive, you would be better off using a try except construction. It is better to ask forgiveness than permission. Also, when performing computations, care to be taken with for loops. If you can, use numpy operations for huge performance impact (sometimes x1000!).

Thus developers must follow guidelines from the Python Software Foundation. As a quick reference:

• For text: PEP 8
• For documentation: PEP 257
• Use reStructuredText formatting: PEP 287

And for a more Pythonic code: PEP 20 Last but not least, avoid common pitfalls: Anti-patterns

Linter

Appart from normal unit and integration tests, you can perform a static analysis of the code using pylint:

pylint batman --rcfile=setup.cfg --ignore-patterns='gp_1d_sampler.py','RBFnet.py','TreeCut.py','resampling.py'

This allows to spot naming errors for example as well as style errors.

Testing

Testing your code is paramount. Without continuous integration, you cannot guaranty the quality of the code. Some minor modification on a module can have unexpected implications. With a single commit, everything can go south! The master branch, and normally the develop branch, are always on a passing state. This means that you should be able to checkout from them an use BATMAN without any errors.

The library pytest is used. It is simple and powerfull. Checkout their doc and replicate constructs from existing tests. If you are not already in love with it, you will soon be. All tests can be launched using:

coverage run -m pytest --basetemp=./TMP_CI batman/tests test_cases

This command fires coverage at the same time. The output consists in tests results and coverage report.

Note

Tests will be automatically launched when you will push your branch to the server. So you only have to run locally your new tests or the one you think you should.

GIT

You can find the development model at http://nvie.com/posts/a-successful-git-branching-model/ Please read this page and stick to it. The master and develop branches are protected and dedicated to the manager only. Release and hotfix branches are mandatory.

If you want to add a modification, create a new branch branching off develop. Then you can create a merge request on gitlab. From here, the fun beggins. You can commit any change you feel, start discussions about it, etc.

1. Clone this copy to your local disk:

   $ git clone git@gitlab.com:cerfacs/batman.git
   

2. Create a branch to hold your changes:

   $ git checkout -b my-feature
   

   and start making changes. Never work in the master branch!

3. Work on this copy, on your computer, using Git to do the version control. When you’re done editing, do:

   $ git add modified_files
   $ git commit
   

   to record your changes in Git, then push them to GitHub with:

   $ git push -u origin my-feature
   

4. Finally, follow these instructions to create a merge request from your fork. This will send an email to the committers.

Note

For every commit you push, the linter is launched. After that, if you want to launch all tests, you have to manually run them using the interface button.

Your request will only be considered for integration if in a finished state:

0. Respect python coding rules,
1. Maintain linting score (>9.5/10),
2. The branch passes all tests,
3. Have tests regarding the changes,
4. Maintain test coverage,
5. Have the respective documentation.

Maintainer / core-developer information

Project management

This is an open-source project, thus its development strategy is also open-sourced:

• Project is managed using gitlab’s functionalities.
• For a merge request to be integrated, it must be approved at least by one other developer. After that, only masters can merge the request.
• Development discussions happen on the chat. Meeting reports are also posted here.
• CI is provided by Gitlab CI using custom made Docker images. Relative configuration and definition files are located under .gitlab/continuous_integration. Two images are available on Docker cloud at: tupui/bat_ci_2 and tupui/bat_ci_3.

Making a release

Aside from following the git-flow branching model, here are some additionnal points:

1. Write the changelog (CHANGELOG.rst). Commit counts can be generated using git log <last_release>.. | git shortlog -s -n for sorting by commits.
2. Fix Milestone issues.
3. Change the version number in batman/__init__.py (do not write the ReleaseName).
4. Update the docs configuration file (credit).
5. Compile documentation.
6. Ensure that all deprecations have been taken care of.
7. Update Docker images and upload the python 3 image on Gitlab registry.
8. Make sure that both python 2 and python 3 tests pass on master.
9. Tag master with X.X-ReleaseName (use git tag -a to annotate the tag).
10. Update conda recipe.
11. Share the info on the chat.