How to contribute to OpenFMS

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

Setup your environment

During development we use tools such as autoformatter (fprettify) and linter (fortitude) to keep our code nice and tidy. Instead of having the developer to install these and run them manually, we use a program called prek which does this automatically on every commit.

1. Install prek

2. Run prek install in your local OpenFMS repository to install prek's pre-commit hook:

From now on, prek will execute hooks defined in prek.toml before every commit. You can also run the hooks manually at any point:

❯ prek run -a
don't commit to branch.................................Passed
check yaml.............................................Passed
check for added large files............................Passed
check for merge conflicts..............................Passed
check that executables have shebangs...................Passed
fortitude..............................................Passed
Check module usage.....................................Passed
Autoformat code........................................Passed

To run only autoformatter

❯ prek run -a format
Autoformat code........................................Passed

See prek documentation for more details.

Code style

Here's a quick summary of our code style that we try to adhere to (especially in new code):

• use implicit none everywhere, no exceptions! This is enforced by the compiler in CI.
• each function/subroutine argument should have the intent attribute.
• use real(DefReal) for real numbers, integer(DefInt) for integers and complex(DefComp) for complex numbers. The DefXXX constants indicating the kind (precision) are defined in GlobalModule.
• 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

Code formatting is enforced using fprettify formatter, and you don't need to think about it for the most part. Here's a quick summary of our formatting style, as it is defined in .fprettify.rc config file.

• use 3 spaces for indentation, no tabs.
• 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 commenting.
  • use an exclamation mark to start a comment

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.

Inspecting Git history

To ignore bulk insignificant changes in git blame history (e.g. whitespace changes), configure git blame to ignore commits specified in .git-blame-ignore-revs file.

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

This is done automatically in GitHub UI.

Building the developer documentation

Building the docs is straightforward:

1. Install FORD with your favorite python package manager
2. Execute ford ford_config.md

That's it.