Contributing

General

There are some general coding conventions that the CatLearn repository adheres to. These include the following:

  • Code should support Python 2.7, 3.4 and higher.
  • Code should adhere to the pep8 and pyflakes style guides.
  • Tests are run using TravisCI and coverage tracked using Coveralls.
  • When new functions are added, tests should be written and added to the CI script.
  • Documentation is hosted on Read the Docs at http://catlearn.readthedocs.io.
  • Should use NumPy style docstrings.

Git Setup

We adhere to the git workflow described here, if you are considering contributing, please familiarize yourself with this. It is a bad idea to develop directly on the on the main CatLearn repository. Instead, fork a version into your own namespace on Github with the following:

  • Fork the repository and then clone it to your local machine.

    $ git clone https://github.com/SUNCAT-Center/CatLearn.git
    
  • Add and track upstream to the local copy.

    $ git remote add upstream https://github.com/SUNCAT-Center/CatLearn.git
    

All development can then be performed on the fork and a merge request opened into the upstream when appropriate. It is normally best to open merge requests as soon as possible, as it will allow everyone to see what is being worked on and comment on any potential issues.

Development

The following workflow is recommended when adding some new functionality:

  • Before starting any new work, always sync with the upstream version.

    $ git fetch upstream
    $ git checkout master
    $ git merge upstream/master --ff-only
    
  • It is a good idea to keep the remote repository up to date.

    $ git push origin master
    
  • Start a new branch to do work on.

    $ git checkout -b branch-name
    
  • Once a file has been changed/created, add it to the staging area.

    $ git add file-name
    
  • Now commit it to the local repository and push it to the remote.

    $ git commit -m 'some descriptive message'
    $ git push --set-upstream origin branch-name
    
  • When the desired changes have been made on your fork of the repository, open up a merge request on Github.

Environment

It is highly recommended to use pipenv for handling dependencies and the virtual environment, more information can be found here. Once installed, go to the root directory of CatLearn and use:

$ pipenv shell

From here it is possible to install and upgrade all the dependencies:

$ pipenv install --dev
$ pipenv update

There are a number of packages that may be important for the development cycle, these are installed with the --dev flag. There are then two ways to install additional dependencies required for new functionality, etc:

$ pipenv install package
$ pipenv install --dev package

The first command will install the package as a dependency for everyone using the code, e.g. people who install CatLearn with pip would be expected to also install this dependency. The second line will only install a package for developers. This workflow can even be used to keep the requirements.txt file up-to-date:

$ pipenv lock -r > requirements.txt

When complete, use exit to quit the virtualenv.

Docker

A docker image is included in the repository. It is sometimes easier to develop within a controlled environment such as this. In particular, it is possible for other developers to attain the same environment. To run CatLearn in the docker container, use the following commands:

$ docker build -t catlearn .
$ docker run -it catlearn bash

This will load up the CatLearn directory. To check that everything is working correctly simply run the following:

$ python2 test/test_suite.py
$ python3 test/test_suite.py

This will run the test_suite.py script with python version 2 and 3, respectively. If one version of python is preferred over the other, it is possible to create an alias as normal with:

$ alias python=python3

Use ctrl+d to exit.

To make changes to this, it is possible to simply edit the Dockerfile. To list the images available on the local system, use the following:

$ docker images
$ docker inspect REPOSITORY

It is a good idea to remove old images. This can be performed using the following lines:

$ docker rm $(docker ps -q -f status=exited)
$ docker rmi $(docker images -q -f "dangling=true")

Testing

When writing new code, please add some tests to ensure functionality doesn’t break over time. We look at test coverage when merge requests are opened and will expect that coverage does not decrease due to large portions of new code not being tested. In CatLearn we just use the built-in unittest framework.

When commits are made, the CI will also automatically test if dependencies are up to date. This test is allowed to fail and will simply return a warning if a module in requirements.txt is out of date. This shouldn’t be of concern and is mostly in place for us to keep track of changes in other code bases that could cause problems.

If changes are being made that change some core functionality, please run the tutorials/test_notebooks.py script. In general, the tutorials involve more demanding computations and thus are not run with the CI. The test_notebooks.py script will run through the various tutorials and make sure that they do not fail.

Tutorials

Where appropriate please consider adding some tutorials for new functionality. It would be great if they were written in jupyter notebook form, allowing for some detailed discussion of what is going on in the code.