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.
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
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
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:
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 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!
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.
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.
You can find the development model at http://nvie.com/posts/a-successful-git-branching-model/
Please read this page and stick to it.
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
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.
Clone this copy to your local disk:
$ git clone email@example.com:cerfacs/batman.git
Create a branch to hold your changes:
$ git checkout -b my-feature
and start making changes. Never work in the
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
Finally, follow these instructions to create a merge request from your fork. This will send an email to the committers.
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:
- Respect python coding rules,
- Maintain linting score (>9.5/10),
- The branch passes all tests,
- Have tests regarding the changes,
- Maintain test coverage,
- Have the respective documentation.
Maintainer / core-developer information¶
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:
Making a release¶
Aside from following the git-flow branching model, here are some additionnal points:
- Write the changelog (
CHANGELOG.rst). Commit counts can be generated using
git log <last_release>.. | git shortlog -s -nfor sorting by commits.
- Fix Milestone issues.
- Change the version number in
batman/__init__.py(do not write the ReleaseName).
- Update the docs configuration file (credit).
- Compile documentation.
- Ensure that all deprecations have been taken care of.
- Update Docker images and upload the python 3 image on Gitlab registry.
- Make sure that both python 2 and python 3 tests pass on master.
- Tag master with X.X-ReleaseName (use
git tag -ato annotate the tag).
- Share the info on the chat.