diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c6dbfd95f5..a45b82b7050 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -339,64 +339,54 @@ Thus, contributors should be aware of the following rules for blank lines: ### Include statement grouping +The concrete ordering will be done by `clang-format`. +Here are the rules that `clang-format` will follow. In general, all include statements should be present on the top of the file, -ordered in the following groups, with two blank lines between each group: +ordered in the following groups, with *one* blank lines between each group: -1. Related header file (e.g. `core/foo/bar.hpp` included in `core/foo/bar.cpp`, +1. Main header file (e.g. `core/foo/bar.hpp` included in `core/foo/bar.cpp`, or in the unit test`core/test/foo/bar.cpp`) 2. Standard library headers (e.g. `vector`) 3. Executor specific library headers (e.g. `omp.h`) 4. System third-party library headers (e.g. `papi.h`) -5. Local third-party library headers -6. Public Ginkgo headers -7. Private Ginkgo headers +5. Public Ginkgo headers +6. Local headers _Example_: A file `core/base/my_file.cpp` might have an include list like this: ```c++ -#include - +#include "ginkgo/core/base/my_file.hpp" #include #include #include - #include - #include - -#include "third_party/blas/cblas.hpp" -#include "third_party/lapack/lapack.hpp" - +#include +#include #include #include #include - #include "core/base/my_file_kernels.hpp" ``` #### Main header -This section presents general rules used to define the main header attributed to -the file. In the previous example, this would be ` #include -`. +This section presents the handling of the main header attributed to a file. +For a given file, the main header is the header that contains the declarations of the +functions, classes, etc., which are implemented in this file. +In the previous example, this would be ` #include +"ginkgo/core/base/my_file.hpp"`. +The `clang-format` tool figures out the main header. The only intervention form +a contributor is to *always* include the main header using `"..."`. -General rules: -1. Some fixed main header. -2. components: - - with `_kernel` suffix looks for the header in the same folder. - - without `_kernel` suffix looks for the header in `core`. -3. `test/utils`: looks for the header in `core` -4. `core`: looks for the header in `ginkgo` -5. `test` or `base`: looks for the header in `ginkgo/core` -6. others: looks for the header in `core` +Please note that this only applies to implementation files, so files ending in `.cpp` or `.cu`. -_Note_: Please see the detail in the `dev_tools/scripts/config`. #### Some general comments. @@ -405,13 +395,6 @@ _Note_: Please see the detail in the `dev_tools/scripts/config`. When compiling with `GINKGO_CHECK_CIRCULAR_DEPS` enabled, this property is explicitly checked. 3. The recommendations of the `iwyu` (Include what you use) tool can be used to make sure that the headers are self-sufficient and that the compiled files ( `.cu`, `.cpp`, `.hip.cpp` ) include only what they use. A [CI pipeline](https://gitlab.com/ginkgo-project/ginkgo-public-ci/-/jobs/584358356) is available that runs with the `iwyu` tool. Please be aware that this tool can be incorrect in some cases. -#### Automatic header arrangement - -1. `dev_tools/script/format_header.sh` will take care of the group/sorting of - headers according to this guideline. -2. `make format_header` arranges the header of the modified files in the branch. -3. `make format_header_all` arranges the header of all files. - ### Other Code Formatting not handled by ClangFormat