This is an automated email from the ASF dual-hosted git repository. aaronai pushed a commit to branch feature/enable_markdown_lint in repository https://gitbox.apache.org/repos/asf/rocketmq-clients.git
commit f7d1e456110632ee1433979b3b7086aff0d0e8f9 Author: Aaron Ai <[email protected]> AuthorDate: Sun Sep 4 16:27:49 2022 +0800 Enable markdown lint --- .github/workflows/markdown_lint.yml | 20 ++++++ README.md | 2 +- cpp/README.md | 64 ++++++++++++----- cpp/docs/gtest.md | 14 ++-- cpp/docs/test_coverage.md | 8 ++- style/markdown/config.yml | 135 ++++++++++++++++++++++++++++++++++++ 6 files changed, 216 insertions(+), 27 deletions(-) diff --git a/.github/workflows/markdown_lint.yml b/.github/workflows/markdown_lint.yml new file mode 100644 index 0000000..4769947 --- /dev/null +++ b/.github/workflows/markdown_lint.yml @@ -0,0 +1,20 @@ +name: Markdown Lint +on: + pull_request: + types: [opened, reopened, synchronize] + push: + branches: + - master +jobs: + lint-changelog: + name: Lint changelog file + runs-on: ubuntu-latest + steps: + - name: Check out code + uses: actions/checkout@v2 + - name: Lint changelog file + uses: avto-dev/markdown-lint@v1 + with: + config: "./style/markdown/config.yml" + args: "**/*.md" + ignore: "./cpp_thrid_party/**/*.md" diff --git a/README.md b/README.md index 75851ab..aee60ef 100644 --- a/README.md +++ b/README.md @@ -59,4 +59,4 @@ Provide cloud-native and robust solutions for Java, C++, C#, Golang, Rust and al [codecov-golang-image]: https://img.shields.io/codecov/c/gh/apache/rocketmq-clients/master?flag=golang&label=Golang%20Coverage&logo=codecov [codecov-url]: https://codecov.io/gh/apache/rocketmq-clients/branch/master/ [maven-image]: https://maven-badges.herokuapp.com/maven-central/org.apache.rocketmq/rocketmq-client-java/badge.svg -[maven-url]: https://maven-badges.herokuapp.com/maven-central/org.apache.rocketmq/rocketmq-client-java \ No newline at end of file +[maven-url]: https://maven-badges.herokuapp.com/maven-central/org.apache.rocketmq/rocketmq-client-java diff --git a/cpp/README.md b/cpp/README.md index 8b7796b..3e1bd67 100644 --- a/cpp/README.md +++ b/cpp/README.md @@ -1,11 +1,13 @@ [](https://github.com/lizhanhui/rocketmq-client-cpp/actions/workflows/main.yml) + ### Introduction + Apache RocketMQ supports two styles of APIs to acknowledge messages once they are successfully processed. 1. Selective Acknowledgement For each logical message queue(aka, topic partition), SDK manages offsets locally and periodically syncs committed offset to brokers in charge. 2. Per Message Acknowledgement - On consumption of each message, SDK acknowledge it to the broker instantly. Broker is responsible of managing consuming progress. + On consumption of each message, SDK acknowledge it to the broker instantly. Broker is responsible of managing consuming progress. Either of them is widely adopted by products. Per message acknowledgement simplifies SDK implementation while selective approach is more performant considering that fewer RPCs are required. @@ -14,23 +16,29 @@ Either of them is widely adopted by products. Per message acknowledgement simpli This SDK is built on top of [gRPC](https://grpc.io/). [Protocol Buffers](https://developers.google.com/protocol-buffers) is used to serialize application messages. ### Type Hierarchy + Classes of this project are designed to be interface oriented.  This paradigm makes dependency injection possible. DI is especially helpful when writing unit tests. ### Core Concepts +  ### Code Style + Generally, we follow [Google C++ Code Style](https://google.github.io/styleguide/cppguide.html). A few exceptions are made to maintain API compatibility. + 1. C++ exception is only allowed in the outer wrapper classes, for example, DefaultMQProducer, DefaultMQConsumer. 2. C++ --std=c++11 is preferred. We intend to maintain the same compiler compatibility matrix to [those of gRPC](https://github.com/grpc/grpc/blob/master/BUILDING.md) 3. Smart pointers are preferred where it makes sense. Use raw pointers only when it is really necessary. -### Dependency Management +### Dependency Management + Considering SDK built on top of gRPC, ensure it is really necessary before introducing a third-party library. Check [gRPC deps](https://github.com/grpc/grpc/blob/master/bazel/grpc_deps.bzl) and [gRPC extra deps](https://github.com/grpc/grpc/blob/master/bazel/grpc_extra_deps.bzl) first! When introducing a third-party dependency or raising version of a dependency, make sure it is back-off friendly. For example, + ``` if "com_google_googletest" not in native.existing_rules(): http_archive( @@ -46,38 +54,46 @@ if "com_google_googletest" not in native.existing_rules(): ### How To Build #### Build with Bazel -[Google Bazel](https://bazel.build/) is the primary build tool we supported, Please follow [bazel installation guide](https://docs.bazel.build/versions/main/install.html). +[Google Bazel](https://bazel.build/) is the primary build tool we supported, Please follow [bazel installation guide](https://docs.bazel.build/versions/main/install.html). 1. Build - From the workspace, + From the workspace, + ``` bazel build //... ``` + 2. Run Unit Tests From the workspace, + ``` bazel test //... ``` #### Build with CMake + 1. Make sure you have installed a modern CMake 3.13+ and C++ compilation toolchain that at least supports C++11; 2. Following [gRPC installation instructions](https://grpc.io/docs/languages/cpp/quickstart/) to install grpc. - Note: - * Remember to `export MY_INSTALL_DIR=$HOME/grpc` as our primary CMakeLists.txt hints + Note: + * Remember to `export MY_INSTALL_DIR=$HOME/grpc` as our primary CMakeLists.txt hints ```cmake list(APPEND CMAKE_PREFIX_PATH $ENV{HOME}/grpc) ``` + If your grpc is installed somewhere else yet non-standard, please adjust accordingly. - * When configure grpc, use your pre-installed system package if possible; + * When configure grpc, use your pre-installed system package if possible; + ```shell cmake -DCMAKE_INSTALL_PREFIX=$HOME/grpc -DgRPC_SSL_PROVIDER=package -DgRPC_ZLIB_PROVIDER=package ``` + A few more options are involved. Check CMakeLists.txt of grpc + ```cmake # Providers for third-party dependencies (gRPC_*_PROVIDER properties): # "module": build the dependency using sources from git submodule (under third_party) @@ -114,20 +130,23 @@ if "com_google_googletest" not in native.existing_rules(): 3. Example programs uses [gflags](https://github.com/gflags/gflags) to parse command arguments. Please install it to $HOME/gflags as CMakeLists.txt has the following find package statements + ```cmake # Assume gflags is install in $HOME/gflags list(APPEND CMAKE_PREFIX_PATH $ENV{HOME}/gflags) find_package(gflags REQUIRED) ``` - -4. OpenSSL development package is also required. + +4. OpenSSL development package is also required. 5. Run the following commands to build from ${YOUR_GIT_REPOSITORY}/cpp directory + ```shell mkdir build && cd build cmake -DOPENSSL_ROOT_DIR=/usr/local/Cellar/[email protected]/1.1.1q .. make -j $(nproc) ``` + 6. Static archive and dynamic linked libraries are found in the build directory. ### Run Examples @@ -137,37 +156,42 @@ if "com_google_googletest" not in native.existing_rules(): #### Publish messages to broker servers Publish standard messages to your topic synchronously + ``` bazel run //examples:example_producer -- --topic=YOUR_TOPIC --access_point=SERVICE_ACCESS_POINT --message_body_size=1024 --total=16 ``` + where `1024` is size of the message body to publish in bytes ------------ - Publish standard messages to your topic asynchronously + ``` bazel run //examples:example_producer_with_async -- --topic=YOUR_TOPIC --access_point=SERVICE_ACCESS_POINT --message_body_size=1024 --total=16 ``` + where `1024` is size of the message body to publish in bytes ------------ - Publish FIFO messages to your topic + ``` bazel run //examples:example_producer_with_fifo_message -- --topic=YOUR_TOPIC --access_point=SERVICE_ACCESS_POINT --message_body_size=1024 --total=16 ``` + where `1024` is size of the message body to publish in bytes ----------- Publish transactional messages + ``` bazel run //examples:example_producer_with_transactional_message -- --topic=YOUR_TOPIC --access_point=SERVICE_ACCESS_POINT --message_body_size=1024 --total=16 ``` - where `1024` is size of the message body to publish in bytes + where `1024` is size of the message body to publish in bytes #### Subscribe messages from broker servers @@ -185,29 +209,31 @@ if "com_google_googletest" not in native.existing_rules(): bazel run //examples:example_simple_consumer -- --topic=YOUR_TOPIC --access_point=SERVICE_ACCESS_POINT --group=YOUR_GROUP_ID ``` +### IDE - +[Visual Studio Code](https://code.visualstudio.com/) + [Clangd](https://clangd.llvm.org/) is the recommended development toolset. -### IDE -[Visual Studio Code](https://code.visualstudio.com/) + [Clangd](https://clangd.llvm.org/) is the recommended development toolset. 1. VSCode + Clangd - - [Clangd](https://clangd.llvm.org/) is a really nice code completion tool. Clangd requires compile_commands.json to work properly. + + [Clangd](https://clangd.llvm.org/) is a really nice code completion tool. Clangd requires compile_commands.json to work properly. To generate the file, we need clone another repository along with the current one. ``` git clone [email protected]:grailbio/bazel-compilation-database.git ``` + From current repository root, ``` ../bazel-compilation-database/generate.sh ``` + Once the script completes, you should have compile_commands.json file in the repository root directory. - LLVM project has an extension for [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd). Please install it from the extension market. + LLVM project has an extension for [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd). Please install it from the extension market. The following configuration entries should be appended to your VSC settings file. + ```text "C_Cpp.intelliSenseEngine": "Disabled", "C_Cpp.autocomplete": "Disabled", // So you don't get autocomplete from both extensions. @@ -218,5 +244,5 @@ if "com_google_googletest" not in native.existing_rules(): ``` 2. CLion + Bazel Plugin - + Bazel also has a plugin for CLion. diff --git a/cpp/docs/gtest.md b/cpp/docs/gtest.md index 0c40d9d..752cdb6 100644 --- a/cpp/docs/gtest.md +++ b/cpp/docs/gtest.md @@ -1,8 +1,12 @@ +# GoogleTest Quickstart + ## Run a single test case + 1. Get all test cases by running tests with --gtest_list_tests -1. Parse this data into your GUI -1. Select test cases you want ro run -1. Run test executable with option --gtest_filter= - +2. Parse this data into your GUI +3. Select test cases you want ro run +4. Run test executable with option --gtest_filter= + ## Run tests multiple times -bazel test --runs_per_test=10 //... \ No newline at end of file + +`bazel test --runs_per_test=10 //...` diff --git a/cpp/docs/test_coverage.md b/cpp/docs/test_coverage.md index 2c836a9..d708f24 100644 --- a/cpp/docs/test_coverage.md +++ b/cpp/docs/test_coverage.md @@ -1,4 +1,7 @@ -### Generate Coverage Data +# Generate Coverage Data and Report + +## Generate Coverage Data + ```text bazel coverage -s \ --instrument_test_targets \ @@ -8,7 +11,8 @@ //src/test/... ``` -### Generate HTML pages +## Generate HTML pages + ```text genhtml bazel-out/_coverage/_coverage_report.dat \ --output-directory coverage_html diff --git a/style/markdown/config.yml b/style/markdown/config.yml new file mode 100644 index 0000000..3340438 --- /dev/null +++ b/style/markdown/config.yml @@ -0,0 +1,135 @@ +default: true # includes/excludes all rules by default + +# Heading levels should only increment by one level at a time <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md001> +MD001: true + +# Heading style <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md003> +MD003: true + +# Unordered list style <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md004> +MD004: true + +# Inconsistent indentation for list items at the same level <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md005> +MD005: true + +# Consider starting bulleted lists at the beginning of the line <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md006> +MD006: true + +# Unordered list indentation <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md007> +MD007: true + +# Trailing spaces <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md009> +MD009: true + +# Hard tabs <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md010> +MD010: true + +# Reversed link syntax <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md011> +MD011: true + +# Multiple consecutive blank lines <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md012> +MD012: true + +# Line length <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md013> +MD013: false + +# Dollar signs used before commands without showing output <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md014> +MD014: false + +# No space after hash on atx style heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md018> +MD018: true + +# Multiple spaces after hash on atx style heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md019> +MD019: true + +# No space inside hashes on closed atx style heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md020> +MD020: true + +# Multiple spaces inside hashes on closed atx style heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md021> +MD021: true + +# Headings should be surrounded by blank lines <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md022> +MD022: true + +# Headings must start at the beginning of the line <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md023> +MD023: true + +# Multiple headings with the same content <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md024> +MD024: + allow_different_nesting: true + +# Multiple top level headings in the same document <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md025> +MD025: true + +# Trailing punctuation in heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md026> +MD026: true + +# Multiple spaces after blockquote symbol <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md027> +MD027: true + +# Blank line inside blockquote <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md028> +MD028: false + +# Ordered list item prefix <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md029> +MD029: + style: 'ordered' + +# Spaces after list markers <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md030> +MD030: true + +# Fenced code blocks should be surrounded by blank lines <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md031> +MD031: true + +# Lists should be surrounded by blank lines <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md032> +MD032: true + +# Inline HTML <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md033> +MD033: true + +# Bare URL used <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md034> +MD034: true + +# Horizontal rule style <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md035> +MD035: + style: '---' + +# Emphasis used instead of a heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md036> +MD036: true + +# Spaces inside emphasis markers <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md037> +MD037: true + +# Spaces inside code span elements <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md038> +MD038: true + +# Spaces inside link text <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md039> +MD039: true + +# Fenced code blocks should have a language specified <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md040> +MD040: true + +# First line in file should be a top level heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md041> +MD041: true + +# No empty links <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md042> +MD042: true + +# Required heading structure <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md043> +MD043: false + +# Proper names should have the correct capitalization <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md044> +MD044: false + +# Images should have alternate text (alt text) <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md045> +MD045: false + +# Code block style <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md046> +MD046: + style: 'fenced' + +# Files should end with a single newline character <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md047> +MD047: true + +# Code fence style <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md048> +MD048: + style: 'backtick' \ No newline at end of file
