Skip to content

Commit

Permalink
[Docs] Update contribution and readme related docs info (apache#7188)
Browse files Browse the repository at this point in the history
  • Loading branch information
@tcodehuber @hawk9821
tcodehuber authored and hawk9821 committed Jul 15, 2024
1 parent 7046e7a commit efcfbc8
Show file tree
Hide file tree
Showing 10 changed files with 83 additions and 93 deletions.
20 changes: 10 additions & 10 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ SeaTunnel addresses common data integration challenges:

- **Real-Time Monitoring**: Offers detailed insights during synchronization.

- **Two Job Development Methods**: Supports coding and visual job management with the [SeaTunnel web project](https://github.com/apache/seatunnel-web).
- **Two Job Development Methods**: Supports coding and visual job management with the [SeaTunnel Web Project](https://github.com/apache/seatunnel-web).

## SeaTunnel Workflow

Expand All @@ -75,7 +75,7 @@ For a list of connectors and their health status, visit the [Connector Status](d

## Getting Started

Download SeaTunnel from the [official website](https://seatunnel.apache.org/download).
Download SeaTunnel from the [Official Website](https://seatunnel.apache.org/download).

Choose your runtime execution engine:
- [SeaTunnel Zeta Engine](https://seatunnel.apache.org/docs/start-v2/locally/quick-start-seatunnel-engine/)
Expand All @@ -84,19 +84,19 @@ Choose your runtime execution engine:

## Use Cases

Explore real-world use cases of SeaTunnel, such as Weibo, Tencent Cloud, Sina, Sogou, and Yonghui Superstores. More use cases can be found on the [SeaTunnel blog](https://seatunnel.apache.org/blog).
Explore real-world use cases of SeaTunnel, such as Weibo, Tencent Cloud, Sina, Sogou, and Yonghui Superstores. More use cases can be found on the [SeaTunnel Blog](https://seatunnel.apache.org/blog).

## Code of Conduct

Participate in this project following the Contributor Covenant [Code of Conduct](https://www.apache.org/foundation/policies/conduct).
Participate in this project in accordance with the Contributor Covenant [Code of Conduct](https://www.apache.org/foundation/policies/conduct).

## Contributors

We appreciate all developers for their contributions. See the [list of contributors](https://github.com/apache/seatunnel/graphs/contributors).
We appreciate all developers for their contributions. See the [List Of Contributors](https://github.com/apache/seatunnel/graphs/contributors).

## How to Compile

Refer to this [document](docs/en/contribution/setup.md) for compilation instructions.
Refer to this [Setup](docs/en/contribution/setup.md) for compilation instructions.

## Contact Us

Expand All @@ -117,7 +117,7 @@ For more information, please refer to [SeaTunnel Web](https://github.com/apache/

## Our Users

Companies and organizations worldwide use SeaTunnel for research, production, and commercial products. Visit our [user page](https://seatunnel.apache.org/user) for more information.
Companies and organizations worldwide use SeaTunnel for research, production, and commercial products. Visit our [Users](https://seatunnel.apache.org/user) for more information.

## License

Expand All @@ -127,23 +127,23 @@ Companies and organizations worldwide use SeaTunnel for research, production, an

### 1. How do I install SeaTunnel?

Follow the [installation guide](https://seatunnel.apache.org/docs/2.3.3/start-v2/locally/deployment/) on our website to get started.
Follow the [Installation Guide](https://seatunnel.apache.org/docs/2.3.3/start-v2/locally/deployment/) on our website to get started.

### 2. How can I contribute to SeaTunnel?

We welcome contributions! Please refer to our [Contribution Guidelines](https://github.com/apache/seatunnel/blob/dev/docs/en/contribution/coding-guide.md) for details.

### 3. How do I report issues or request features?

You can report issues or request features on our [GitHub repository](https://github.com/apache/seatunnel/issues).
You can report issues or request features on our [GitHub Repository](https://github.com/apache/seatunnel/issues).

### 4. Can I use SeaTunnel for commercial purposes?

Yes, SeaTunnel is available under the Apache 2.0 License, allowing commercial use.

### 5. Where can I find documentation and tutorials?

Our [official documentation](https://seatunnel.apache.org/docs) includes detailed guides and tutorials to help you get started.
Our [Official Documentation](https://seatunnel.apache.org/docs) includes detailed guides and tutorials to help you get started.

### 7. Is there a community or support channel?

Expand Down
2 changes: 1 addition & 1 deletion docs/en/command/connector-check.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Connector check command usage
# Connector Check Command Usage

## Command Entrypoint

Expand Down
2 changes: 1 addition & 1 deletion docs/en/command/usage.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Command usage
# Command Usage

## Command Entrypoint

Expand Down
55 changes: 25 additions & 30 deletions docs/en/contribution/coding-guide.md
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,46 @@
# Coding guide
# Coding Guide

This guide documents an overview of the current Apache SeaTunnel modules and best practices on how to submit a high quality pull request to Apache SeaTunnel.

## Modules Overview

| Module Name | Introduction |
|----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| seatunnel-api | SeaTunnel connector V2 API module |
| seatunnel-apis | SeaTunnel connector V1 API module |
| seatunnel-common | SeaTunnel common module |
| seatunnel-connectors | SeaTunnel connector V1 module, currently connector V1 is in a stable state, the community will continue to maintain it, but there will be no major feature updates |
| seatunnel-connectors-v2 | SeaTunnel connector V2 module, currently connector V2 is under development and the community will focus on it |
| seatunnel-core/seatunnel-spark | SeaTunnel core starter module of connector V1 on spark engine |
| seatunnel-core/seatunnel-flink | SeaTunnel core starter module of connector V1 on flink engine |
| seatunnel-core/seatunnel-flink-sql | SeaTunnel core starter module of connector V1 on flink-sql engine |
| seatunnel-core/seatunnel-spark-starter | SeaTunnel core starter module of connector V2 on Spark engine |
| seatunnel-core/seatunnel-flink-starter | SeaTunnel core starter module of connector V2 on Flink engine |
| seatunnel-core/seatunnel-starter | SeaTunnel core starter module of connector V2 on SeaTunnel engine |
| seatunnel-e2e | SeaTunnel end-to-end test module |
| seatunnel-examples | SeaTunnel local examples module, developer can use it to do unit test and integration test |
| seatunnel-engine | SeaTunnel engine module, seatunnel-engine is a new computational engine developed by the SeaTunnel Community that focuses on data synchronization. |
| seatunnel-formats | SeaTunnel formats module, used to offer the ability of formatting data |
| seatunnel-plugin-discovery | SeaTunnel plugin discovery module, used to offer the ability of loading SPI plugins from classpath |
| seatunnel-transforms-v2 | SeaTunnel transform V2 module, currently transform V2 is under development and the community will focus on it |
| seatunnel-translation | SeaTunnel translation module, used to adapt Connector V2 and other computing engines such as Spark Flink etc... |

## How to submit a high quality pull request
| Module Name | Introduction |
|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| seatunnel-api | SeaTunnel connector V2 API module |
| seatunnel-common | SeaTunnel common module |
| seatunnel-connectors-v2 | SeaTunnel connector V2 module, currently connector V2 is under development and the community will focus on it |
| seatunnel-core/seatunnel-spark-starter | SeaTunnel core starter module of connector V2 on Spark engine |
| seatunnel-core/seatunnel-flink-starter | SeaTunnel core starter module of connector V2 on Flink engine |
| seatunnel-core/seatunnel-starter | SeaTunnel core starter module of connector V2 on SeaTunnel engine |
| seatunnel-e2e | SeaTunnel end-to-end test module |
| seatunnel-examples | SeaTunnel local examples module, developer can use it to do unit test and integration test |
| seatunnel-engine | SeaTunnel engine module, seatunnel-engine is a new computational engine developed by the SeaTunnel Community that focuses on data synchronization. |
| seatunnel-formats | SeaTunnel formats module, used to offer the ability of formatting data |
| seatunnel-plugin-discovery | SeaTunnel plugin discovery module, used to offer the ability of loading SPI plugins from classpath |
| seatunnel-transforms-v2 | SeaTunnel transform V2 module, currently transform V2 is under development and the community will focus on it |
| seatunnel-translation | SeaTunnel translation module, used to adapt Connector V2 and other computing engines such as Spark, Flink etc... |

## How To Submit A High Quality Pull Request

1. Create entity classes using annotations in the `lombok` plugin (`@Data` `@Getter` `@Setter` `@NonNull` etc...) to reduce the amount of code. It's a good practice to prioritize the use of lombok plugins in your coding process.

2. If you need to use log4j to print logs in a class, preferably use the annotation `@Slf4j` in the `lombok` plugin.

3. SeaTunnel uses issue to track logical issues, including bugs and improvements, and uses Github's pull requests to manage the review and merge of specific code changes. So making a clear issue or pull request helps the community better understand the developer's intent, the best practice of creating issue or pull request as the following shown:
3. SeaTunnel uses issue to track logical issues, including bugs and improvements, and uses Github's pull requests to manage the review and merge of specific code changes. So making a clear issue or pull request helps the community better understand the developer's intent. The best practice of creating issue or pull request is as the following shown:

> [purpose] [module name] [sub-module name] Description
1. Pull request purpose includes: `Hotfix`, `Feature`, `Improve`, `Docs`, `WIP`.Note that if your pull request's purpose is `WIP`, then you need to use github's draft pull request
1. Pull request purpose includes: `Hotfix`, `Feature`, `Improve`, `Docs`, `WIP`. Note that if your pull request's purpose is `WIP`, then you need to use github's draft pull request
2. Issue purpose includes: `Feature`, `Bug`, `Docs`, `Discuss`
3. Module name: the current pull request or issue involves the name of the module, for example: `Core`, `Connector-V2`, `Connector-V1`, etc.
4. Sub-module name: the current pull request or issue involves the name of the sub-module, for example:`File` `Redis` `Hbase` etc.
5. Description: highly summarize what the current pull request and issue to do, as far as possible to do the name to know the meaning
5. Description: provide a brief, clear summary of the current pull request and issue's main goals and aim for a title that conveys the core purpose at a glance.

Tips:**For more details, you can refer to [issue guide](https://seatunnel.apache.org/community/contribution_guide/contribute#issue) and [pull request guide](https://seatunnel.apache.org/community/contribution_guide/contribute#pull-request)**
Tips:**For more details, you can refer to [Issue Guide](https://seatunnel.apache.org/community/contribution_guide/contribute#issue) and [Pull Request Guide](https://seatunnel.apache.org/community/contribution_guide/contribute#pull-request)**

4. Code segments are never repeated. If a code segment is used multiple times, define it multiple times is not a good option, make it a public segment for other modules to use is a best practice.

5. When throwing an exception, throw the exception along with a hint message and the exception should be smaller in scope.Throwing overly broad exceptions promotes complex error handling code that is more likely to contain security vulnerabilities.For example, if your connector encounters an `IOException` while reading data, a reasonable approach would be to the following:
5. When throwing an exception, throw it along with a hint message and the exception should be smaller in scope. Throwing overly broad exceptions promotes complex error handling code that is more likely to contain security vulnerabilities. For example, if your connector encounters an `IOException` while reading data, a reasonable approach would be to the following:

```java
try {
Expand Down Expand Up @@ -98,7 +93,7 @@ This guide documents an overview of the current Apache SeaTunnel modules and bes
10. If you submit a pull request with a feature that requires updated documentation, always remember to update the documentation.
12. Submit the pull request of connector type can write e2e test to ensure the robustness and robustness of the code, e2e test should include the full data type, and e2e test as little as possible to initialize the docker image, write the test cases of sink and source together to reduce the loss of resources, while using asynchronous features to ensure the stability of the test. A good example can be found at: [MongodbIT.java](https://github.com/apache/seatunnel/blob/dev/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-mongodb-e2e/src/test/java/org/apache/seatunnel/e2e/connector/v2/mongodb/MongodbIT.java)
11. Submit the pull request of connector type can write e2e test to ensure the robustness and robustness of the code, e2e test should include the full data type, and e2e test as little as possible to initialize the docker image, write the test cases of sink and source together to reduce the loss of resources, while using asynchronous features to ensure the stability of the test. A good example can be found at: [MongodbIT.java](https://github.com/apache/seatunnel/blob/dev/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-mongodb-e2e/src/test/java/org/apache/seatunnel/e2e/connector/v2/mongodb/MongodbIT.java)
12. The priority of property permission in the class is set to `private`, and mutability is set to `final`, which can be changed reasonably if special circumstances are encountered.
Expand All @@ -108,7 +103,7 @@ This guide documents an overview of the current Apache SeaTunnel modules and bes
15. If there are multiple `if` process judgments in the code flow, try to simplify the flow to multiple ifs instead of if-else-if.
16. Pull request has the characteristic of single responsibility, not allowed to include irrelevant code of the feature in pull request, once this situation deal with their own branch before submitting pull request, otherwise the Apache SeaTunnel community will actively close pull request
16. Pull request has the characteristic of single responsibility, not allowed to include irrelevant code of the feature in pull request, once this situation deal with their own branch before submitting pull request, otherwise the Apache SeaTunnel community will actively close pull request.
17. Contributors should be responsible for their own pull request. If your pull request contains new features or modifies old features, add test cases or e2e tests to prove the reasonableness and functional integrity of your pull request is a good practice.
Expand Down
Loading

0 comments on commit efcfbc8

Please sign in to comment.