Skip to content

Latest commit

 

History

History
96 lines (59 loc) · 3.58 KB

contribute.rst

File metadata and controls

96 lines (59 loc) · 3.58 KB
Raw

Contribute to snowtools

Developer environment

To contribute to snowtools, you must :

  • use the git versioning tool
  • use PyCharm as code editor
  • work in a branch, deriving from dev (except for simple commits that can be directly done on dev branch)
  • Test your branch on your personal computer and with the test server
  • Ensure new development are tested
  • Ensure you followed guidelines below
  • Ask for a code review before merging

To add the git project to PyCharm directly, click on VCS, then checkout from version control and then git.

Code style

Python code should comply with PEP8 https://www.python.org/dev/peps/pep-0008 style guide. Please check your code before committing. In particular, tabs are prohibited and lines may not exceed 120 characters.

Code tips

Shebangs

If you are writing a script that can be executed, please add the following shebang. Note that you should not point to python as it may not be defined on all platforms, hence you have to point to python3.

#!/usr/bin/env python3

Moreover, all codes must specify the encodign, which have to be utf-8:

# -*- coding: utf-8 -*-

Imports

Please avoid relative imports in snowtools. Absolute imports must start at snowtools package level. For instance, to import the prosimu class from everywhere, write:

from snowtools.utils.prosimu import prosimu

See PEP 8 import section https://www.python.org/dev/peps/pep-0008/#imports for more details on correct import order and other guidelines on imports.

Of course star-imports (from XXX import *) are prohibited.

Documentation and testing

Each modification or code addition must be clearly documented in a docstring so that it could be included in this documentation. Please refer to :ref:`sec-doc` section for the main guidelines.

In addition, each new development should come with tests (unit tests and/or test cases). See :ref:`sec-test` section for main guidelines.

Git commits

For both snowtools and SURFEX projects, all developments must be done in seperated git branches with frequent commit to ensure traceability of your modifications and the ability to include in your own branch the main bugfixes and developments of the main branches.

We recoment to commit only when :

  • You have a state of the code that is self-sufficient (not work in progress that could not be used yet)
  • Tests are passing
  • You have in your commit only changes on one topic (and not mixed changes that are unrelated)

Each commit must contain a clear message that include:

  • The type of commit (bugfix, development, documentation, etc.
  • In few words, the part of the code that is affected
  • The reason of the commit.

The commit message is composed of a title (1st line) that summarize the changes and could be complemented by more detailed description of the changes explaining the reasons of the changes for future generations.

Developpement branches must start from the dev branch and be named dev_<project> where <project> is the name of the project or obviously describe what is inside the branch.

Language

Of course, all comments in the code, documentation and commit message have to be in english.

SURFEX

SURFEX developements must follow the specific coding rules of this project: http://www.cnrm.meteo.fr/surfex-lab/spip.php?rubrique93 Contributions will not be accepted if they do not follow these requirements.