docs: update readme

taosdata · Jan 24, 2025 · cf57515 · cf57515
1 parent 2a47797
commit cf57515
Show file tree

Hide file tree

Showing 2 changed files with 168 additions and 35 deletions.
diff --git a/README-CN.md b/README-CN.md
@@ -1,24 +1,56 @@
-# 简介
+<!-- omit in toc -->
+# TDengine C# Connector
+<!-- omit in toc -->
 
 | Github Action Tests                                                                          | CodeCov                                                                                                                                                   |
 |----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
 | ![actions](https://github.com/taosdata/taos-connector-dotnet/actions/workflows/linux.yml/badge.svg) | [![codecov](https://codecov.io/gh/taosdata/taos-connector-dotnet/graph/badge.svg?token=U30JZYDGMS)](https://codecov.io/gh/taosdata/taos-connector-dotnet) |
 
 [English](README.md) | 简体中文
 
+<!-- omit in toc -->
+## 目录
+<!-- omit in toc -->
+
+- [1. 简介](#1-简介)
+  - [1.1 连接方式](#11-连接方式)
+  - [1.2 dotnet 版本兼容性](#12-dotnet-版本兼容性)
+  - [1.3 支持的平台](#13-支持的平台)
+- [2. 获取驱动](#2-获取驱动)
+- [3. 文档](#3-文档)
+- [4. 前置条件](#4-前置条件)
+- [5. 构建](#5-构建)
+- [6. 测试](#6-测试)
+  - [6.1 运行测试](#61-运行测试)
+  - [6.2 添加用例](#62-添加用例)
+  - [6.3 性能测试](#63-性能测试)
+- [7. 提交 Issue](#7-提交-issue)
+- [8. 提交 PR](#8-提交-pr)
+- [9. 引用](#9-引用)
+- [10. 许可证](#10-许可证)
+
+## 1. 简介
+
 `TDengine.Connector` 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。
 
-`TDengine.Connector` 提供了两种连接方式：
+### 1.1 连接方式
 
 - 原生连接：通过客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接。这种方式需要保证客户端的驱动程序 taosc 和服务端的 taosd 版本保持一致。
 - Websocket 连接： 通过 taosAdapter 组件提供的 WebSocket API 建立与 taosd 的连接，不依赖 TDengine 客户端驱动。
 
-## 支持的平台
+我们推荐使用 WebSocket 连接方式。 详细说明请参考：[连接方式](https://docs.taosdata.com/develop/connect/#%E8%BF%9E%E6%8E%A5%E6%96%B9%E5%BC%8F) 。
+
+### 1.2 dotnet 版本兼容性
+
+- .NET Framework 4.6 及以上版本。
+- .NET 5.0 及以上版本。
+
+### 1.3 支持的平台
 
 - 原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。
 - WebSocket 连接支持所有能运行 .NET 运行时的平台。
 
-# 获取驱动
+## 2. 获取驱动
 
 可以在当前 .NET 项目的路径下，通过 dotnet CLI 添加 Nuget package `TDengine.Connector` 到当前项目。
 
@@ -34,36 +66,65 @@ dotnet add package TDengine.Connector
   </ItemGroup>
 ```
 
-# 文档
-
-- 开发示例请见[开发指南](https://docs.taosdata.com/develop/)
-- 版本历史、TDengine 对应版本以及 API 说明请见[参考手册](https://docs.taosdata.com/reference/connector/csharp/)
+## 3. 文档
 
-# 贡献
+- 开发示例请见[开发指南](https://docs.taosdata.com/develop/)，包含了数据写入、查询、无模式写入、参数绑定和数据订阅等示例。
+- 其他参考信息请见[参考手册](https://docs.taosdata.com/reference/connector/csharp/)，包含了版本历史、TDengine 对应版本以及 API 说明和常见问题等。
 
-鼓励每个人帮助改进这个项目，以下是这个项目的开发测试流程：
-
-## 前置条件
+## 4. 前置条件
 
 * 安装 [.NET SDK](https://dotnet.microsoft.com/download)
 * [Nuget 客户端](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) （可选安装）
 * 安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](https://docs.taosdata.com/develop/connect/#%E5%AE%89%E8%A3%85%E5%AE%A2%E6%88%B7%E7%AB%AF%E9%A9%B1%E5%8A%A8-taosc)
 
-## 构建
+## 5. 构建
 
 1. `dotnet restore` 还原项目依赖。
 2. `dotnet build --no-restore` 构建项目。
 
-## 测试
+## 6. 测试
+
+### 6.1 运行测试
 
 1. 执行测试前确保已经安装 TDengine 服务端，并且已经启动 taosd 与 taosAdapter，数据库干净无数据
 2. 项目目录下执行 `dotnet test` 运行测试，测试会连接到本地的 TDengine 服务器与 taosAdapter 进行测试
+3. 测试成功会打印 `Test Run Successful`，测试失败会打印失败信息 `Test Run Failed`
+
+### 6.2 添加用例
+
+在 `test` 目录下添加测试用例，ADO.NET 的测试用例添加到 `test/Data.Tests`，客户端驱动的测试用例添加到 `test/Driver.Test/Client`。
+用例使用 xunit 框架。
+
+### 6.3 性能测试
+
+性能测试还在开发中。
+
+## 7. 提交 Issue
+
+我们欢迎提交 [GitHub Issue](https://github.com/taosdata/taos-connector-dotnet/issues/new?template=Blank+issue)。 提交时请说明下面信息：
+
+- 问题描述，是否必现
+- 驱动版本
+- 连接参数（不需要服务器地址、用户名和密码）
+- TDengine 版本
+
+## 8. 提交 PR
+
+我们欢迎开发者一起开发本项目，提交 PR 时请参考下面步骤：
+
+1. Fork 本项目，请参考 ([how to fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo))
+2. 从 main 分支创建一个新分支，请使用有意义的分支名称 (`git checkout -b my_branch`)。
+3. 修改代码，保证所有单元测试通过，并增加新的单元测试验证修改。
+4. 提交修改到远端分支 (`git push origin my_branch`)。
+5. 在 GitHub 上创建一个 Pull
+   Request ([how to create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request))。
+6. 提交 PR 后，如果 CI 通过，可以在 [codecov](https://app.codecov.io/gh/taosdata/taos-connector-dotnet/pulls) 页面找到自己 PR 查看覆盖率。
 
-# 引用
+## 9. 引用
 
 - [TDengine 官网](https://www.taosdata.com/)
 - [TDengine GitHub](https://github.com/taosdata/TDengine)
 
-# 许可证
+## 10. 许可证
 
 [MIT License](./LICENSE)
diff --git a/README.md b/README.md
@@ -1,26 +1,60 @@
-# Introduction
+<!-- omit in toc -->
+# TDengine C# Connector
+<!-- omit in toc -->
 
 | Github Action Tests                                                                                 | CodeCov                                                                                                                                                   |
 |-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
 | ![actions](https://github.com/taosdata/taos-connector-dotnet/actions/workflows/linux.yml/badge.svg) | [![codecov](https://codecov.io/gh/taosdata/taos-connector-dotnet/graph/badge.svg?token=U30JZYDGMS)](https://codecov.io/gh/taosdata/taos-connector-dotnet) |
 
 English | [简体中文](README-CN.md)
 
+<!-- omit in toc -->
+## Table of Contents
+<!-- omit in toc -->
+
+- [1. Introduction](#1-introduction)
+    - [1.1 Connection Methods](#11-connection-methods)
+    - [1.2 .NET Version Compatibility](#12-net-version-compatibility)
+    - [1.3 Supported Platforms](#13-supported-platforms)
+- [2. Get the Driver](#2-get-the-driver)
+- [3. Documentation](#3-documentation)
+- [4. Prerequisites](#4-prerequisites)
+- [5. Build](#5-build)
+- [6. Testing](#6-testing)
+    - [6.1 Test Execution](#61-test-execution)
+    - [6.2 Test Case Addition](#62-test-case-addition)
+    - [6.3 Performance Testing](#63-performance-testing)
+- [7. Submitting Issues](#7-submitting-issues)
+- [8. Submitting PRs](#8-submitting-prs)
+- [9. References](#9-references)
+- [10. License](#10-license)
+
+
+## 1. Introduction
+
 `TDengine.Connector` is the C# language connector provided by TDengine. C# developers can use it to develop C# application software that accesses TDengine cluster data.
 
-`TDengine.Connector` provides two connection methods:
+### 1.1 Connection Methods
 
 - Native Connection: Establishes a connection directly with the server program taosd through the client driver taosc.
   This method requires the client driver taosc and the server taosd to be of the same version.
 - WebSocket Connection: Establishes a connection with taosd through the WebSocket API provided by the taosAdapter
   component, without relying on the TDengine client driver.
 
-## Supported Platforms
+We recommend using the WebSocket connection method. For detailed instructions, please refer
+to: [Connection Methods](https://docs.tdengine.com/developer-guide/connecting-to-tdengine/#connection-methods).
+
+### 1.2 .NET Version Compatibility
+
+- .NET Framework 4.6 and above
+- .NET 5.0 and above
 
-- Native Connection: Supported platforms are consistent with those supported by the TDengine client driver.
-- WebSocket Connection: Supports all platforms that can run the .NET runtime.
+### 1.3 Supported Platforms
 
-# Get the Driver
+- The platforms supported by the native connection are consistent with those supported by the TDengine client driver.
+- WebSocket connections support all platforms that can run .NET.
+
+## 2. Get the Driver
 
 Nuget package `TDengine.Connector` can be added to the current project through dotnet CLI under the path of the current .NET project.
 
@@ -36,40 +70,78 @@ You can also modify the `.csproj` file of the current project and add the follow
    </ItemGroup>
 ```
 
-# Documentation
-
-- For development examples, see the [Developer Guide](https://docs.tdengine.com/developer-guide/).
-- For version history, TDengine version compatibility, and API documentation, see
-  the [Reference Manual](https://docs.tdengine.com/tdengine-reference/client-libraries/csharp/).
+## 3. Documentation
 
-# Contributing
+- For development examples, see [Developer Guide](https://docs.tdengine.com/developer-guide/), which includes examples
+  of data writing, querying, schemaless writing, parameter binding, and data subscription.
+- For other reference information,
+  see [Reference Manual](https://docs.tdengine.com/tdengine-reference/client-libraries/csharp/), which includes version
+  history, data types, example programs, API descriptions, and FAQs.
 
-We encourage everyone to help improve this project. Below is the development and testing process for this project:
-
-## Prerequisites
+## 4. Prerequisites
 
 * Install [.NET SDK](https://dotnet.microsoft.com/download)
 * [Nuget Client](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) (optional installation)
 * Install the TDengine client driver. For specific steps, please refer
   to [Installing the client driver](https://docs.tdengine.com/develop/connect/#install-client-driver-taosc)
 
-## Building
+## 5. Build
 
 1. `dotnet restore` Restore the project's dependencies.
 2. `dotnet build --no-restore` Build the project.
 
-## Testing
+## 6. Testing
+
+### 6.1 Test Execution
 
 1. Before running tests, ensure that the TDengine server is installed and that `taosd` and `taosAdapter` are running.
    The database should be empty.
 2. In the project directory, run `dotnet test` to execute the tests. The tests will connect to the local TDengine
    server and taosAdapter for testing.
+3. If the tests pass, `Test Run Successful` will be printed. If the tests fail, the failure information
+   `Test Run Failed`
+   will be printed.
+
+### 6.2 Test Case Addition
+
+Add test cases in the `test` directory. Add ADO.NET test cases to `test/Data.Tests` and client driver test cases to
+`test/Driver.Test/Client`.
+The test cases use the xunit framework.
+
+### 6.3 Performance Testing
+
+Performance testing is in progress.
+
+## 7. Submitting Issues
+
+We welcome the submission
+of [GitHub Issue](https://github.com/taosdata/taos-connector-dotnet/issues/new?template=Blank+issue). When
+submitting, please provide the following information:
+
+- Description of the issue and whether it is consistently reproducible
+- Driver version
+- Connection parameters (excluding server address, username, and password)
+- TDengine version
+
+## 8. Submitting PRs
+
+We welcome developers to contribute to this project. Please follow the steps below to submit a PR:
+
+1. Fork this project. Please refer
+   to [how to fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
+2. Create a new branch from the main branch with a meaningful branch name (`git checkout -b my_branch`).
+3. Modify the code, ensure all unit tests pass, and add new unit tests to verify the changes.
+4. Push the changes to the remote branch (`git push origin my_branch`).
+5. Create a Pull Request on GitHub. Please refer
+   to [how to create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
+6. After submitting the PR, if the CI passes, you can find your PR on
+   the [codecov](https://app.codecov.io/gh/taosdata/taos-connector-dotnet/pulls) page to check the coverage.
 
-# References
+## 9. References
 
 - [TDengine Official Website](https://tdengine.com/)
 - [TDengine GitHub](https://github.com/taosdata/TDengine)
 
-# License
+## 10. License
 
 [MIT License](./LICENSE)