You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@rocketmq.apache.org by aa...@apache.org on 2022/09/04 12:19:11 UTC
[rocketmq-clients] 01/01: Fix markdown lint style
This is an automated email from the ASF dual-hosted git repository.
aaronai pushed a commit to branch fix_docs_lint
in repository https://gitbox.apache.org/repos/asf/rocketmq-clients.git
commit a055299561a4dd20b880a4e9211f46fef733f9c6
Author: Aaron Ai <ya...@gmail.com>
AuthorDate: Sun Sep 4 20:18:03 2022 +0800
Fix markdown lint style
---
.github/workflows/markdown_lint.yml | 2 +-
README.md | 4 ++
cpp/README.md | 107 ++++++++++++++++++++++--------------
cpp/docs/gtest.md | 14 +++--
cpp/docs/test_coverage.md | 8 ++-
csharp/README.md | 34 +++++-------
docs/observability.md | 2 +-
docs/workflow.md | 6 +-
golang/README.md | 21 ++-----
9 files changed, 108 insertions(+), 90 deletions(-)
diff --git a/.github/workflows/markdown_lint.yml b/.github/workflows/markdown_lint.yml
index 915a939..bda32f7 100644
--- a/.github/workflows/markdown_lint.yml
+++ b/.github/workflows/markdown_lint.yml
@@ -14,4 +14,4 @@ jobs:
- name: Install mardkdownlint
run: npm install -g markdownlint-cli
- name: Run markdownlint
- run: markdownlint -c ./style/markdown/config.yml -i ./cpp/third_party **/*.md
+ run: markdownlint -c ./style/markdown/config.yml -i ./cpp/third_party -i ./rust/src/pb/README.md **/*.md
diff --git a/README.md b/README.md
index aee60ef..3f7705e 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,10 @@ Provide cloud-native and robust solutions for Java, C++, C#, Golang, Rust and al
| Push consumer with concurrent message listener | ✅ | ✅ | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 |
| Push consumer with FIFO message listener | ✅ | ✅ | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 |
+## Contributing
+
+Similar to other projects of Apache RocketMQ, any attempt to make this project better is welcome, including but not limited to filing a bug report, correcting type error or document writing to complete feature implementation. Do not hesitate to make a pull request if this project catches your attention.
+
## Related
* [rocketmq](https://github.com/apache/rocketmq): The implementation of server-side.
diff --git a/cpp/README.md b/cpp/README.md
index 8b7796b..746b935 100644
--- a/cpp/README.md
+++ b/cpp/README.md
@@ -1,37 +1,45 @@
-[](https://github.com/lizhanhui/rocketmq-client-cpp/actions/workflows/main.yml)
-### Introduction
+# The C++ Implementation
+
+## 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.
-### Transport Layer
+## Transport Layer
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
+## 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
+## Core Concepts
+
-### Code Style
+## 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,
-```
+
+```starlark
if "com_google_googletest" not in native.existing_rules():
http_archive(
name = "com_google_googletest",
@@ -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,
+
+ ```starlark
bazel build //...
```
+
2. Run Unit Tests
From the workspace,
- ```
+
+ ```starlark
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/openssl@1.1/1.1.1q ..
make -j $(nproc)
```
+
6. Static archive and dynamic linked libraries are found in the build directory.
### Run Examples
@@ -137,77 +156,83 @@ if "com_google_googletest" not in native.existing_rules():
#### Publish messages to broker servers
Publish standard messages to your topic synchronously
- ```
+
+ ```starlark
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
- ```
+
+ ```starlark
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
- ------------
+ where `1024` is size of the message body to publish in bytes
+ ---
Publish FIFO messages to your topic
- ```
+
+ ```starlark
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
- ```
+
+ ```starlark
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
Consume messages through Message Listener
- ```
+ ```starlark
bazel run //examples:example_push_consumer -- --topic=YOUR_TOPIC --access_point=SERVICE_ACCESS_POINT --group=YOUR_GROUP_ID
```
- ------------
-
+ ---
Consume messages through raw, atomic API
- ```
+ ```starlark
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.
- ```
+ ```sh
git clone git@github.com:grailbio/bazel-compilation-database.git
```
+
From current repository root,
- ```
+ ```sh
../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 +243,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..3fc97a1 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..e0795e5 100644
--- a/cpp/docs/test_coverage.md
+++ b/cpp/docs/test_coverage.md
@@ -1,4 +1,7 @@
-### Generate Coverage Data
+# Test Covergge 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/csharp/README.md b/csharp/README.md
index bdc2bba..33589d2 100644
--- a/csharp/README.md
+++ b/csharp/README.md
@@ -1,44 +1,36 @@
-[](https://github.com/lizhanhui/rocketmq-client-csharp/actions/workflows/main.yml)
+# The C# Implementation
-Introduction
---------------
-Project rocketmq-client-csharp is targeted to implement C# binding in native C# code. At the current moment, it is still a work-in-progress project. Do not use it in production till it grows mature enough.
+## Introduction
+
+This is still a work-in-progress project. Do not use it in production till it grows mature enough.
+
+## Architecture
-Architecture
---------------
Basically, this project would follow the same paradigm of [rocketmq-client-cpp v5.0.0](https://github.com/apache/rocketmq-client-cpp/tree/main). Namely, we would build the whole client following protocols described in [rocketmq-apis](https://github.com/apache/rocketmq-apis) on top of [gRPC-dotnet](https://github.com/grpc/grpc-dotnet), utilizing [Protocol buffers](https://developers.google.com/protocol-buffers) to serialize and deserialize data in transmission.
+## How to build
-How to build
------------------
Layout of this project roughly follows [this guide](https://docs.microsoft.com/en-us/dotnet/core/tutorials/library-with-visual-studio-code?pivots=dotnet-5-0). The solution contains a class library, a unit test module and an example console module.
1. Install dotnet tool chains following instructions [here](https://dotnet.microsoft.com/en-us/download);
2. Visual Studio Code with official C# plugin is used during development;
Assuming you are at the home of this repository,
-#### Build
+
+### Build
```sh
dotnet build
```
-#### Run Unit Tests
+### Run Unit Tests
+
```sh
dotnet test -l "console;verbosity=detailed"
```
-#### Run Examples
+### Run Examples
+
```sh
dotnet run -p examples
```
-
-License
-------------------
-This project follows [Apache License Version 2.0](./LICENSE).
-
-How to contribute
-------------------
-Similar to other Apache RocketMQ projects, we welcome contributions in various ways, from filing a bug report, correcting type error, document writing to complete feature implementation. Any attempt to make this project better is welcome.
-
-If this project catches your attention, do not hesitate to make a pull request.
\ No newline at end of file
diff --git a/docs/observability.md b/docs/observability.md
index 136c055..55a7bf5 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -12,4 +12,4 @@
| -------- | ----------------------------------------- |
| CPP | `$HOME/logs/rocketmq/client.log` |
| C# | `$HOME/logs/rocketmq/rocketmq-client.log` |
-| Java | `$HOME/logs/rocketmq/rocketmq-client.log` |
\ No newline at end of file
+| Java | `$HOME/logs/rocketmq/rocketmq-client.log` |
diff --git a/docs/workflow.md b/docs/workflow.md
index 9344f41..7cfa614 100644
--- a/docs/workflow.md
+++ b/docs/workflow.md
@@ -11,9 +11,7 @@ Different from previous clients, the new version adds some preparations during t
Failure of any preparation will result in the failure of client startup.
-<div align="center">
-<img src="./artwork/client_startup_process.png" width="80%">
-</div>
+
In details, the **server-client telemetry** provides a channel to upload the local settings and to overwrite the client settings.
@@ -84,4 +82,4 @@ For TRANSACTIONAL messages, the publishing will not be retried if failure is enc
<div align="center">
<img src="./artwork/message_receiving_and_process_in_simple_consumer.png" width="50%">
-</div>
\ No newline at end of file
+</div>
diff --git a/golang/README.md b/golang/README.md
index e1ed513..ace88de 100644
--- a/golang/README.md
+++ b/golang/README.md
@@ -1,16 +1,14 @@
-Introduction
---------------
+# The Golang Implementation
+
Project github.com/apache/rocketmq-clients/golang is targeted to implement with golang. At the current moment, it is still a work-in-progress project. Do not use it in production till it grows mature enough.
-Architecture
---------------
-We build the following protocols described in [rocketmq-apis](https://github.com/apache/rocketmq-apis) on top of [gRPC-go](https://github.com/grpc/grpc-go), utilizing [Protocol buffers](https://developers.google.com/protocol-buffers) to serialize and deserialize data in transmission.
+## Architecture
+We build the following protocols described in [rocketmq-apis](https://github.com/apache/rocketmq-apis) on top of [gRPC-go](https://github.com/grpc/grpc-go), utilizing [Protocol buffers](https://developers.google.com/protocol-buffers) to serialize and deserialize data in transmission.
-How to use
------------------
+## Quick Start
-#### Installation
+### Installation
With [Go modules](https://go.dev/doc/go1.11#modules)(Go 1.11+), simply add the following import to your code, and then `go [build|run|test]` will automatically fetch the necessary dependencies.
@@ -22,10 +20,3 @@ Otherwise, to install the `golang` package, run the following command:
```console
$ go get -u github.com/apache/rocketmq-clients/golang
```
-
-
-How to contribute
-------------------
-Similar to other Apache RocketMQ projects, we welcome contributions in various ways, from filing a bug report, correcting type error, document writing to complete feature implementation. Any attempt to make this project better is welcome.
-
-If this project catches your attention, do not hesitate to make a pull request.
\ No newline at end of file