7. Developers Guide

7.1. Repository

  • Inq uses git for development, the main repository is hosted in Gitlab: https://gitlab.com/npneq/inq/. Cloning the repository is achieved via git clone –recurse-submodules git@gitlab.com:npneq/inq.git. We are not going enter into details on how to use git or GitLab here, only in things that are particular to how inq works. Something important to have in mind is that git is not svn, trying to use it like that will lead to more pain in the long run.

  • It is important that before contributing to inq, you check that your git push mode is set to current (or simple), and not matching (it can lead developers to do things they don’t intend to). To set your push mode to current use the following command:

git config --global push.default current

  • The branch master contains the latest development version of inq. However, you cannot directly commit to it. For any changes you need to create a new branch that later will be merged back into `master`. The advantage of this is that changes are divided into units of work that can be evaluated before merging.

  • The procedure to integrate changes into inq is the following:

    • Create and switch to a new branch in your local repository (git checkout -b name_of_the_new_branch).

    • Make the changes you want to do, test locally if you can, and commit the changes to your new branch (generally git commit …).

    • Push the changes to the repository (git push), git will show a special link.

    • Create a new “merge request” (MR) in GitLab. (Merge Requests are similar to pull requests (PR) in GitHub.) This is done by opening a link just shown. Give it a meaningful title and a description of what the branch does. If you expect to make more changes to the branch, add “DRAFT:” to the beginning of the title. That tells other developers this is not done yet and shouldn’t be merged right now.

    • You can keep push ing changes to the branch and they will be considered in the merge request.

    • Each time you push changes, GitLab will run the continuous integration suite (CI) for inq. The CI compiles inq with different compilers and different architectures and runs some tests. This helps detect any basic problems in your changes. You won’t be able to merge unless all the CI test are completed successfully.

    • Once you are satisfied with the changes and the CI is happy, you can merge into the main branch. If you don’t have permission to merge, a maintainer can do it for you.

    • It is your responsibility to test the new code, in particular all new code or feature should be accompanied with new tests.

  • When doing commits consider the following:

    • Several small commits are preferred to a single big one. Small commits make it simple to understand the changes.

    • Do not include several unrelated changes in a single commit.

    • Write meaningful commit descriptions. Seriously, we read them.

    • Do not push to GitLab after every single commit. Pushing triggers the CI to run that takes time and computational resources. In some cases a single commit per push might be okay (if you are fixing something in the CI for example), but as a rule of thumb, one push for hour of work is reasonable.

    • Conversely, do not keep changes local without pushing them. Other developers should know what your are doing.

    • Do as much test locally as your development system permits, this will save time and overloading of the CI system, not to mention the extra coverage it might provide regarding your particular build system. For example you can have the following ./pre-push script

(mkdir -p .build.g++.dbg  && cd .build.g++.dbg  && ../configure --prefix=$HOME                                                                            && make -j 12 && make install && make test -j 5) || exit 666
(mkdir -p .build.clang++  && cd .build.clang++  && ../configure --prefix=$HOME               --disable-debug                                              && make -j 12 && make install && make test -j 5) || exit 666
(mkdir -p .build.nvcc     && cd .build.nvcc     && ../configure --prefix=$HOME --enable-cuda --disable-debug --pass-thru -DCMAKE_CUDA_HOST_COMPILER=g++-9 && make -j 10 && make install && make test -j 5) || exit 666

Here you can put as many combinations of compilers and flags as you want and as much as it is reasonable to run as a pre validation to git push. Furthermore you can locally link ln -s ../../pre-push .git/hooks/pre-push to automatically execute this script before pushing changes.

7.2. Coding

  • Minimize the use of comments, make the code more clear instead of writing and maintaining comments.

  • Whitespace (spaces, tabs and line breaks) should be used to help convey the meaning visually as best as possible for most text editors.

  • We use [tabs for indentation and spaces for alignment](https://web.archive.org/web/20070712225742/http://blogs.msdn.com/cyrusn/archive/2004/09/14/229474.aspx). Most editors allow to adjust the visual length of the tab character (for example 2 or 4), giving some degree of visual options to the developer without affecting the source. We believe that there is no strict one-to-one correspondence between code and whitespace, so be wary of bulk formatting tools or strict rules. At the moment, all inq files should have /* -*- indent-tabs-mode: t -*- */ in the first line to ensure the editor is using tabs and not whitespaces. Many editors default to whitespaces for indentation.

  • To make the code more readable spaces should be used round operators like =, ==, <, <=, +=, *=, ‘+’, ‘-’. Also add a space after a ,.

  • Do not add spaces around * or /, before ( or [, unless to further clarify associativity.

  • When possible, declare the variable in the same line it is used. Almost always use auto (AAA) unless the explicit type is necessary.

  • Do not use single letter variables or type names.

  • For objects names: use lowercase and underscore ‘_’ to separate words (this_is_a_variable). The only exception is template arguments that should be Capitalized (ExampleOfATemplatedType). Ideally template names should convey concepts, either mathematical (e.g. RealMatrix) or in the specific domain of the problem (e.g. Field).

  • Functions and classes should do “one thing” and do it well.

  • Use “rule of 10” when possible, (a function/class/namespace with more than 10 lines/members/classes should be decomposed into smaller functions/classes/namespaces). Choose their names carefully given the context.

7.3. Debugging code

In order to debug the code you can use gdb. To debug in parallel use the following command

mpirun -np 2 gnome-terminal --wait -- gdb -ex run --args ./tests/executable

You will get two terminal windows one for each process.