docs: separate contributing guide, update links (#1318)

erigontech · Jul 10, 2023 · 47284ec · 47284ec
1 parent 3dee250
commit 47284ec
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 76 deletions.
diff --git a/README.md b/README.md
@@ -2,22 +2,18 @@
 
 C++ implementation of the Ethereum Execution Layer (EL) protocol based on the [Erigon Thorax architecture].
 
-[![CircleCI](https://circleci.com/gh/torquem-ch/silkworm.svg?style=shield)](https://circleci.com/gh/torquem-ch/silkworm)
+[![Linux](https://circleci.com/gh/torquem-ch/silkworm.svg?style=shield)](https://circleci.com/gh/torquem-ch/silkworm)
 [![macOS](https://github.com/torquem-ch/silkworm/actions/workflows/macOS.yml/badge.svg)](https://github.com/torquem-ch/silkworm/actions/workflows/macOS.yml)
 [![Windows](https://github.com/torquem-ch/silkworm/actions/workflows/windows.yml/badge.svg)](https://github.com/torquem-ch/silkworm/actions/workflows/windows.yml)
-[![CodeCov](https://codecov.io/gh/torquem-ch/silkworm/branch/master/graph/badge.svg)](https://codecov.io/gh/torquem-ch/silkworm)
-[![GitHub](https://img.shields.io/github/license/torquem-ch/silkworm.svg)](https://github.com/torquem-ch/silkworm/blob/master/LICENSE)
-![semver](https://img.shields.io/badge/semver-2.0.0-blue)
 
 ## Table of Contents
 
-- [About Silkworm](#about-silkworm)
-- [Obtaining Source Code](#obtaining-source-code)
-- [Building on Linux & macOS](#building-on-linux--macos)
-- [Building on Windows](#building-on-windows)
-- [Codemap](#codemap)
-- [Testing Silkworm](#testing-silkworm)
-- [Style Guide](#style-guide)
+- [About Silkworm](#about)
+- [Obtaining Source Code](#source-code)
+- [Building on Linux & macOS](#build-on-unix)
+- [Building on Windows](#build-on-windows)
+- [Testing Silkworm](#testing)
+- [Contributing Guide](docs/CONTRIBUTING.md)
 - [License](#license)
 
 
@@ -35,7 +31,7 @@ Silkworm is under active development and hasn't reached the alpha phase yet.
 Hence, there have been no releases so far.
 
 
-<a name="source"></a>
+<a name="source-code"></a>
 ## Obtaining Source Code
 
 To obtain Silkworm source code for the first time:
@@ -55,7 +51,7 @@ git submodule update --init --recursive
 ```
 
 
-<a name="build_on_unix"></a>
+<a name="build-on-unix"></a>
 ## Building on Linux & macOS
 
 Building Silkworm requires:
@@ -82,6 +78,20 @@ cmake ..
 ```
 (In the future you don't have to run `cmake ..` again.)
 
+
+A custom Conan "profile" can be passed via a cmake argument, for example: 
+
+    cmake .. -DCONAN_PROFILE=macos_arm_clang_13_debug
+
+will use "debug" configuration builds of dependencies.
+
+See available profiles in [cmake/profiles](cmake/profiles).
+
+The conan packages could also be pre-installed using [conan install](https://docs.conan.io/1/reference/commands/consumer/install.html):
+
+    conan install --install-folder=build/conan --build=missing --profile=cmake/profiles/macos_arm_clang_13_debug .
+
+
 Then run the build itself
 ```
 make -j
@@ -102,7 +112,8 @@ or [Ethereum EL Tests]
 cmd/test/ethereum
 ```
 
-<a name="build_on_windows"></a>
+
+<a name="build-on-windows"></a>
 ## Building on Windows
 
 **Note! Windows builds are maintained for compatibility/portability reasons. However, due to the lack of 128-bit integers support by MSVC, execution performance is inferior when compared to Linux builds.**
@@ -126,24 +137,8 @@ Use the following steps to detect/enable/disable memory compression:
 * To disable memory compression : `Disable-MMAgent -mc` and reboot
 * To enable memory compression : `Enable-MMAgent -mc` and reboot
 
-## Codemap
-
-Apart from the submodules and some auxiliary directories, Silkworm contains the following components:
-* [`cmd`](./cmd)
-  <br /> The source code of Silkworm executable binaries.
-* [`silkworm/core`](./silkworm/core)
-  <br /> This module contains the heart of the Ethereum protocol logic as described by the [Yellow Paper].
-  Source code within `core` is compatible with WebAssembly and cannot use C++ exceptions.
-* [`silkworm/node`](./silkworm/node)
-  <br /> This module contains the database, the [staged sync] and other logic necessary to function as an Ethereum node.
-  This module depends on the `core` module.
-* [`silkworm/sentry`](./silkworm/sentry)
-  <br /> This module implements the networking and protocol stacks for `Sentry` component for an Ethereum node based on [Erigon Thorax architecture].
-  This module depends on both the `core` and `node` modules.
-* [`silkworm/wasm`](./silkworm/wasm)
-  <br /> This module allows the `core` the run on WebAssembly. This module depends on both the `core` and `node` modules.
-
-<a name="testing_silkworm"></a>
+
+<a name="testing"></a>
 ## Testing Silkworm
 
 **Note: at current state of development Silkworm can't actually sync the chain like Erigon does.**
@@ -187,49 +182,18 @@ $env:STOP_AT_BLOCK=15000000
 ./cmd/silkworm.exe
 ```
 
-## Use Conan as Package Manager
-
-A custom Conan "profile" can be passed via a cmake argument, for example: 
-
-    cmake .. -DCONAN_PROFILE=macos_arm_clang_13_debug
-
-will use "debug" configuration builds of dependencies.
-
-See available profiles in [cmake/profiles](cmake/profiles).
-
-The conan packages could also be pre-installed using [conan install](https://docs.conan.io/1/reference/commands/consumer/install.html):
-
-    conan install --install-folder=build/conan --build=missing --profile=cmake/profiles/macos_arm_clang_13_debug .
-
-
-<a name="guide"></a>
-## Style Guide
-
-We use the standard C++20 programming language.
-We adhere to [Google's C++ Style Guide] with the following differences:
-
-* C++20 rather than C++17.
-* `snake_case()` for function names.
-* .cpp & .hpp file extensions for C++; .c & .h are reserved for C.
-* `using namespace foo` is allowed inside .cpp files, but not inside headers.
-* Exceptions are allowed outside the `core` library.
-* User-defined literals are allowed.
-* Maximum line length is 120, indentation is 4 spaces – see [.clang-format](.clang-format).
-* Use `#pragma once` in the headers instead of the classic `#ifndef` guards.
-
 
+<a name="license"></a>
 ## License
 
 Silkworm is licensed under the terms of the Apache license.
 See [LICENSE](LICENSE) for more information.
 
 
-[CMake]: http://cmake.org
 [Ethereum EL Tests]: https://github.com/ethereum/tests
 [Erigon]: https://github.com/ledgerwatch/erigon
 [Erigon Thorax architecture]: https://github.com/ledgerwatch/erigon#key-features
 [GMP]: http://gmplib.org
-[Google's C++ Style Guide]: https://google.github.io/styleguide/cppguide.html
 [libmdbx]: https://github.com/erthink/libmdbx
 [staged sync]: https://github.com/ledgerwatch/erigon/blob/devel/eth/stagedsync/README.md
 [Visual Studio]: https://www.visualstudio.com/downloads

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+# Contributing Guide
+
+We use the standard C++20 programming language.
+We adhere to [Google's C++ Style Guide] with the following differences:
+
+* C++20 rather than C++17.
+* `snake_case()` for function names.
+* .cpp & .hpp file extensions for C++; .c & .h are reserved for C.
+* `using namespace foo` is allowed inside .cpp files, but not inside headers.
+* Exceptions are allowed outside the `core` library.
+* User-defined literals are allowed.
+* Maximum line length is 120, indentation is 4 spaces. Use `make fmt` to reformat according to the code style.
+* Add Apache copyright banners. Use `make lint` to check the proper banner style.
+* Use `#pragma once` in the headers instead of the classic `#ifndef` guards.
+* [clang-tidy](https://clang.llvm.org/extra/clang-tidy/) runs on CI. The report is attached to the "ARTIFACTS" section of the linux-clang-tidy job that can be found [here](https://app.circleci.com/pipelines/github/torquem-ch/silkworm?branch=master).
+
+
+## Codemap
+
+Apart from the submodules and some auxiliary directories, Silkworm contains the following components:
+* [`cmd`](./cmd)
+  <br /> The source code of Silkworm executable binaries.
+* [`silkworm/core`](./silkworm/core)
+  <br /> This module contains the heart of the Ethereum protocol logic as described by the [Yellow Paper].
+  Source code within `core` is compatible with WebAssembly and cannot use C++ exceptions.
+* [`silkworm/node`](./silkworm/node)
+  <br /> This module contains the database, the [staged sync] and other logic necessary to function as an Ethereum node.
+  This module depends on the `core` module.
+* [`silkworm/sentry`](./silkworm/sentry)
+  <br /> This module implements the networking and protocol stacks for `Sentry` component for an Ethereum node based on [Erigon Thorax architecture].
+  This module depends on both the `core` and `node` modules.
+* [`silkworm/wasm`](./silkworm/wasm)
+  <br /> This module allows the `core` the run on WebAssembly. This module depends on both the `core` and `node` modules.
+
+
+[Google's C++ Style Guide]: https://google.github.io/styleguide/cppguide.html
diff --git a/lgtm.yml b/lgtm.yml