Merge branch 'feature/contribution-guide' into 'master'

[doc] Add preliminary contribution guide and style guide

See merge request !992

CONTRIBUTING.md

+# Contribution guidelines for DuMu<sup>x</sup>
+
+DuMu<sup>x</sup> and DUNE are community projects and we are happy about all forms of external contributions.
+Here are many easy things that you can do, like
+
+* read the documentation and tell us where and how it should be improved,
+* try to install DuMu<sup>x</sup> on your platform and report bugs if it doesn’t work,
+* fix bugs and open merge requests or send us patches.
+
+If you decide to contribute code please read this contribution guide.
+
+## Style guide
+When contributing code to DuMu<sup>x</sup> please follow the [style guide](doc/styleguide.md). Your work will enjoy much smoother sailing if you stick to it with your changes. DuMu<sup>x</sup> is a pretty large project, and a consistent way of doing things really helps a lot when trying to find your way around the code.
+
+## Contributing
+
+You should get your changes to us in the following way:
+
+* Get an account for our GitLab instance (you might need to contact us if you can't create projects at first login).
+* Fork the core module that you want to contribute to, just as you would do on GitHub.
+* Push your changes to your fork on some branch.
+* Open a merge request using the branch you pushed your changes to as the source branch and the master of the DuMu<sup>x</sup> repository
+  as the target branch. GitLab will usually ask you about opening a merge request if you browse it right after pushing to some branch.
+* Follow the discussion on the merge request to see what improvements should be done to the branch before merging.
+* If you have developer status you don't need to do a fork and you can create branches directly.
+
+If you have any questions or complaints about this workflow of contributing to DuMu<sup>x</sup>, please ask on the
+[DuMu<sup>x</sup> mailing list](https://listserv.uni-stuttgart.de/mailman/listinfo/dumux).
+
+## Git
+* Use Git to your advantage!
+* Check out this [great tutorial](https://www.atlassian.com/git/tutorials/setting-up-a-repository) in order to learn how to use it.
+* Also check out [Dune's Git best practices](https://www.dune-project.org/doc/guides/git_best_practices/).
+* Everything should compile after every single commit.
+* Make small commits with changes limited to a single issue / change.
+* Format commit messages as follows:
+
+    ```
+    [topic] Brief description of the change
+
+    Long description containing the status quo,
+    the changes the commit introduces and why.
+    ```
+
+    where `topic` is usually a foldername, `[assembly]`, a model `[2p2c]`, or any other topic, e.g. `[cmake]`.
+
+* Use `git rebase -i master` to update branches to the changes on the master branch.
+* Feature branches should be called `feature/my-bla-feature`.
+* Bugfix branches should be called `fix/issue-554`.
+* Cleanup branches should be called `cleanup/remove-deprecated-bla`.
+* Use lower case letters only, and hyphens to separate things.
+
+## GitLab
+* Open issues for bugs / discussions / feature requests.
+* Give issues a meaningful title, focus each issue on a single topic, describe what the problem is and what you tried.
+* Open merge request for changes to be merged into master or other branches. Pushing to master is disabled.
+* Give merge requests a meaningful title, describe what the problem is, how this is fixed with this merge request.
+* If you don't have the permissions to open branches, you might have permissions to do a fork in your own GitLab namespace and open a merge request from your fork into the dumux repository.
+* Merge requests get reviewed by at least one main developer.
+* If continuous integration (GitLabCI / BuildBot) is enabled for merge requests, the pipeline has to pass before merging anything to master.
+
+## Patches
+
+* Patches can be supplied via the mailing list,
+* should be formatted with git format-patch.
+* TODO: How to format patches

doc/handbook/4_guidelines.tex

@@ -2,125 +2,5 @@
 \label{sc_guidelines}
 Writing code in a readable manner is very important, especially
 for future code developers (e.g. for adding features, debugging, etc.).
-This section is inspired by the DUNE coding guidelines
-\url{https://www.dune-project.org/dev/codingstyle/}, which is strongly recommended.
-
-\subsection{Documentation:}
-Please document freely what each part of your code \emph{should} do. All comments/documentation
-is in English.
-We proclaim the Doc-Me Dogma, which means whatever you do, please document
-it at least with:
-\begin{lstlisting}[style=DumuxCode]
-  \todo Please doc me!
-\end{lstlisting}
-That way at least the absence of documentation is documented, and it is easier
-to get rid of it systematically.
-In the following we will describe several ways for
-commenting code in \Dumux.\\
-There are four ways to comment a \textbf{single line} of code:
-\begin{lstlisting}[style=DumuxCode]
-Line of code 1 // Short comment on line of code 1 that will not show in doxygen
-Line of code 2 //!< Short comment on line of code 2 that will show in doxygen
-//! Short comment on the following line (line of code 3) that will show in doxygen
-Line of code 3
-/*!
- * Longer comment on line of code 4
- * with several lines of length
- * that will show in doxygen
- */
-Line of code 4
-\end{lstlisting}
-The third and fourth of the above shown options can also be used to document functions with
-neither method parameters nor return value.\\
-For doxygen to be able to group the \textbf{files} correctly, please add before the headerguard:
-\begin{lstlisting}[style=DumuxCode]
-/*!
- * \file
- * \ingroup GroupName
- * \brief A short description of the file.
- */
-
-#ifndef HEADERGUARD
-#define HEADERGUARD
-\end{lstlisting}
-For doxygen to be able to group the \textbf{classes} correctly, please add before each class:
-\begin{lstlisting}[style=DumuxCode]
-/*!
- * \ingroup GroupName
- * \brief A short description of the class.
- *
- * Optional detailed description of the class
- * over several lines.
- */
-template <class TypeTag>
-\end{lstlisting}
-For an overview over all available groups and to add new groups please
-see the file\\ \texttt{doc/doxygen/modules.txt} from the \texttt{dumux} module.\\
-Please add before each \textbf{function} with method parameters or return value:
-\begin{lstlisting}[style=DumuxCode]
-/*!
- * \brief A short description of the function.
- *
- * Optional detailed description of the function
- * over several lines.
- *
- * \param paramName Very short description of paramName
- * \return returnName Very short description of returnName
- */
-paramType functionName(paramType paramName)
-{
-   ...
-   return returnName
-}
-\end{lstlisting}
-Furthermore, please comment \textit{all}:
-\begin{itemize}
-  \item Template Parameters
-  \item Exceptions thrown by a method
-  \item Method parameters which are not self-explanatory should always
-        have a meaningful comment at calling sites. Example:
-  \begin{lstlisting}[style=DumuxCode]
-    localResidual.eval(/*includeBoundaries=*/true);
-  \end{lstlisting}
-\end{itemize}
-
-\subsection{Naming:}
-To avoid duplicated types or variables and for a better understanding and usability
-of the code we have the following naming conventions:
-\begin{itemize}
-\item \textbf{Variables/Functions \ldots}
-  \begin{itemize}
-  \item start in \emph{lower} case and contain letters.
-  \item \emph{CamelCase}: if the name consists of  several words, then
-        the first letter of a new word is capital.
-  \item \emph{Self-Explaining}: in general abbreviations should be avoided (write saturation in stead of S)
-  \item \emph{Abbreviations}: If and only if a single letter that represents an
-         abbreviation or index is followed by a single letter (abbreviation or index),
-         CamelCase is \textbf{not} used. An inner-word underscore is only permitted if
-         it symbolizes a fraction line. Afterwards, we continue with lower case, i.e.
-         the common rules apply to both enumerator and denominator. Examples:
-  \begin{itemize}
-      \item \texttt{pw} but \texttt{pressureW} $\rightarrow$ because ``pressure'' is a word.
-      \item \texttt{srnw} but \texttt{sReg} $\rightarrow$ because ``reg'' is not an
-            abbreviation of a single letter. ``n'' abbreviates ``non'',
-             ``w'' is ``wetting'', so not CamelCase.
-      \item \texttt{pcgw} but \texttt{dTauDPi} $\rightarrow$ Both ``Tau'' and ``Pi''
-            are words, plus longer than a letter.
-      \item \textbf{But:} \texttt{CaCO3} The only exception: chemical formulas are
-            written in their chemically correct way $\rightarrow$ \texttt{CaCO3}
-  \end{itemize}
-  \end{itemize}
-\item \textbf{Private Data Variables:} Names of private data variables end with an
-      underscore and are the only variables that contain underscores.
-\item \textbf{Type names:} For type names, the same rules as for variables apply. The
-      only difference is that the \emph{first letter is capital}.
-\item \textbf{Files:} File names should consist of \emph{lower case} letters
-      exclusively. Header files get the suffix \texttt{.hh}, implementation files the
-      suffix \texttt{.cc}
-\item \textbf{The Exclusive-Access Macro:} Every header file traditionally begins
-      with the definition of a preprocessor constant that is used to make sure that
-      each  header file is only included once. If your header file is called
-      'myheaderfile.hh', this constant should be DUMUX\_MYHEADERFILE\_HH.
-\item \textbf{Macros:} The use of preprocessor macros is strongly discouraged. If you
-      have to use them for whatever reason, please use capital letters only.
-\end{itemize}
+For the style guide and instructions how to contribute to \Dumux visit
+\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}.

doc/styleguide.md

+# Style guide
+
+This style guide is taken, modified and enhanced from [DUNE](https://dune-project.org/dev/codingstyle/).
+
+## General formatting
+
+* Use 4 spaces indent (no tabs, not 2 spaces).
+* _Trailing whitespace_: source files may not contain trailing whitespace to reduce
+  the amount of noise in diffs and during merges.
+* In contrast to the remainder of the coding style guidelines, these code formatting
+  rules are (partially) enforced automatically with a pre-commit hook. Due to the
+  distributed nature of Git, this hook can only check your commits once they arrive
+  in the central repository, so it is important to make your local Git repository check
+  your commits as well. The dunecontrol script will automatically install such a pre-commit
+  hook for you.
+
+
+## C++
+
+### Documentation
+
+* Please document freely what each part of your code _should_ do. Document assumptions.
+* All comments/documentation in English.
+* We proclaim the Doc-Me dogma, which means whatever you do, please document it at least with
+
+    ```c++
+    //! \todo Please doc me!
+    ```
+
+* We use Doxygen to generate documentation from the source code
+
+    ```c++
+    int lineOfCode = 1; // Short comment on line of code 1 that will _not_ show in doxygen
+    int lineOfCode = 2; //!< Short comment on line of code 2 that will show in doxygen
+    //! Short comment on the following line (line of code 3) that will show in doxygen
+    int lineOfCode = 3;
+    /*!
+     * Longer comment on line of code 4
+     * with several lines of length
+     * that will show in doxygen
+     */
+    int lineOfCode = 4;
+    ```
+
+* Files always contain the following documentation header before the headerguard:
+
+    ```c++
+    /*!
+     * \file
+     * \ingroup GroupName
+     * \brief A short description of the file.
+     */
+    #ifndef DUMUX_HEADERGUARD_HH
+    #define DUMUX_HEADERGUARD_HH
+    ```
+
+    where `GroupName` is a doxygen module group, click [here](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/doc/doxygen/modules.txt) for an overview of existing groups.
+
+* Each class should be documented using the following style:
+
+    ```c++
+    /*!
+     * \ingroup GroupName
+     * \brief A short description of the class.
+     *
+     * Optional detailed description of the class
+     * over several lines.
+     *
+     * \tparam T very short description of the template parameter T
+     */
+    template<class T>
+    class MyClass {};
+    ```
+
+* Each free function and class member function should be documented using the following style:
+
+    ```c++
+    /*!
+     * \brief A short description of the function.
+     *
+     * Optional detailed description of the function
+     * over several lines.
+     *
+     * \tparam paramType Very short description of paramType
+     * \param paramName Very short description of paramName
+     * \return returnName Very short description of returnName
+     */
+    template<typename paramType>
+    paramType functionName(const paramType& paramName)
+    {
+      ...
+      return returnName
+    }
+    ```
+
+* Also document non-obvious function parameters at call site:
+
+    ```c++
+    localResidual.eval(/*includeBoundaries=*/true);
+    ```
+
+* Possible exceptions thrown by a function.
+
+### Naming schemes
+
+* Avoid abbreviation, i.e. write `saturation` instead of `s`.
+
+
+#### Variables / Functions
+
+* CamelCase starting with a lower case letter, each new word starting with a capital letter.
+* No underscores (except private data members, see below).
+* Exception: If and only if a single letter that represents an
+             abbreviation or index is followed by a single letter (abbreviation or index),
+             CamelCase is __not__ used.
+* Examples:
+    - `pw` but `pressureW`, because "pressure" is a word.
+    - `srnw` but `sReg`, because "Reg" is not an abbreviation consisting of a single letter.
+    - `pcgw` but `dTauDPi`, because "Tau" and "Pi" are words and longer than one letter.
+    - `CaCO3`, because we write chemical formulas in their chemically sensible way.
+
+* Private data members end with an underscore.
+
+#### Typenames / Classes / Aliases / Namespaces
+
+* Same rules as for variables, except the first letter is capital.
+
+
+#### Filenames / Folders
+
+* Lower case letters (filenames, but not foldernames may contain underscores).
+* Header files get the suffix `.hh`, implementation files the suffix `.cc`.
+* Every header file contains a unique header guard. The name should mimic the folder structure and contain the filename,
+  i.e. for a file `common/myfile.hh` it should be
+
+    ```c++
+    #ifndef DUMUX_COMMON_MYFILE_HH
+    #define DUMUX_COMMON_MYFILE_HH
+    ```
+
+#### Macros
+* The use of preprocessor macros is strongly discouraged. If you have to use them for whatever reason, please use capital letters only.
+
+
+### Indent
+
+* The default indent is 4 spaces (no tabs, not 2 spaces).
+
+### Formatting
+
+* Curly brackets that open or close a scope are on a separate line (except for [namespaces](#Namespaces)).
+* There should be a space between `if`,`else if`,`switch` and the condition.
+* `if`,`else if`,`switch` can omit brackets if the expression is only one line.
+
+    ```c++
+    // comment for if block, space between if and (enableGravity)
+    if (enableGravity)
+    {
+        Scalar b = 1.0;
+        return b*gravity_[dimWorld-1];
+    }
+
+    // comment for else-block
+    else
+        return 1.0; // ok, one-liner
+    ```
+
+### Namespaces
+
+* Open curly brackets on the same line.
+* Do not indent the code inside the namespace.
+* Comment closing curly brackets uniquely.
+
+    ```c++
+    namespace Dumux {
+    namespace Properties {
+
+    bool here = true;
+        bool nothere = false; // not like this
+
+    } // end namespace Properties
+    } // end namespace Dumux
+    ```
+
+* Use a `Detail` namespace for hiding implementation details, e.g. for template meta programming.
+
+### Includes
+
+* Space between `#include` and path.
+* C++ standard library includes first, then Dune, then others, then DuMu<sup>x</sup>.
+* Always use project relative paths.
+    - Exception: the other header is in the same folder and closely related (`#include "volumevariables.hh"`).
+
+    ```c++
+    #include <type_traits>
+    #include <dune/common/fvector.hh>
+    #include <dumux/common/exceptions.hh>
+    ```
+
+### Property system
+
+* Prefer class templates with regular template arguments over class templates with a `TypeTag` as template argument.
+
+### Exception
+
+* The use of exceptions for error handling is encouraged.
+* There is a variety of DuMu<sup>x</sup> and Dune-specific exceptions you can throw.
+* All derive (possibly indirectly) from the class `Dune::Exception` in dune-common.
+
+
+
+## Files and folders
+
+* Try to order your new header into the existing directory structure.
+* Headers are named like the classes they contain (usually one class per file, exception: closely tied helper classes / functions).
+* Headers are named lower case only (using underscores only if absolutely necessary for readability).
+* Folder names are lower case only.
+* Tests should be called after model and discretization scheme using underscores and lower case only, e.g.
+
+    ```
+    test_1p_tpfa
+    test_2p2c_box_infiltration
+    ```
+
+## CMake
+
+* Use named arguments only.
+* TODO
+
+## Python
+
+* TODO