Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
90 lines (68 loc) · 3.39 KB

CONTRIBUTING.md

File metadata and controls

90 lines (68 loc) · 3.39 KB

How to contribute to ABIN

Thanks for contributing to our code! 💜 Here's a couple of guidelines that you should keep in mind.

Setup your environment

To setup your environment, run:

cd dev_scripts && ./setup_dev_environment.sh

Read through the script first to see what it does (it's not long, I promise). It is useful especially if you use VIM as your text editor, as it sets it up to use our code style rules. If you use a different editor, we welcome if you contribute your config files!

You also should install fprettify, which is a Python program that we use for autoformatting the Fortran code. Due to a large variability of Python installation options and environments, we do not try to install it automatically. For example, you can use pip (or pip3 if your default is Python2).

pip install --upgrade fprettify

Install dev dependencies

  • Some ABIN functionality requires external libraries; see README.md for details.
  • To build and run Unit Tests, you will need to install pFUnit library, you can use dev_scripts/install_pfunit.sh.

Code style

Here's a quick summary of our code style that we try to adhere to:

  • use implicit none everywhere, no exceptions!
  • each function/subroutine argument should have the intent attribute.
  • use REAL(DP) for real numbers, the DP constant indicating the kind (precision) is defined in modules.F90
  • variables and subroutines in modules should be private by default, use private attribute,e.g.
module mod_my_module
  private
  integer :: public_var
  integer :: private_var
  public :: public_var
  public :: public_subroutine
contains
 subroutine public_subroutine
    ...
 end subroutine public_subroutine
end module mod_my_module

Code formatting

We're using fprettify to automatically format our code; you should use it too! That way you don't need to worry about it and just apply fprettify at the end, like so:

fprettify src/file_you_modified.F90 -c .fprettify.rc --case 1 1 1 2

Here's a quick summary of our formatting style, as it is defined in .fprettify.rc config file.

  • maximum line-length should be 100 characters.
  • use 3 spaces for indentation, no tabs.
  • use capital letters only for defined constants (e.g. those from module mod_const). We use lower case for everything else.
  • use snake_case for naming your subroutines and variables. (not camelCase)
  • use C-style relational operators (< > == /=) instead of the old FORTRAN style (.gt. .lt.)
  • comments should start at the same indentation level as the code they are commnenting.
    • use an exclamation mark to start a comment

Inspecting Git history

To ignore bulk whitespace changes in blame history, use:

git blame --ignore-revs-file .git-blame-ignore-revs

or to do it automatically:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Unfortunately, this is not yet supported in the GitHub UI, but Github UI already allows to browse git blame a bit.

Submitting code changes

Last but not least, to get your code merged to the main repository, please open a Pull Request (PR) on Github. If you're not familiar with Pull Requests, take a look here.

It's super easy, barely an inconvenience! (assuming basic familiarity with Git)