This is an automated email from the ASF dual-hosted git repository.
psxjoy pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fesod.git
The following commit(s) were added to refs/heads/main by this push:
new bd4d6f92 docs: update contributing in the root directory of the
repository. (#609)
bd4d6f92 is described below
commit bd4d6f925be4d05d306b576140ace4a60cd7e4d1
Author: DeleiGuo <[email protected]>
AuthorDate: Sat Sep 27 15:54:11 2025 +0800
docs: update contributing in the root directory of the repository. (#609)
Co-authored-by: Shuxin Pan <[email protected]>
---
CONTRIBUTING.md | 305 ++++++++++++++++++++++++++++++++++++++------------------
1 file changed, 210 insertions(+), 95 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cd7d4c94..623e73b2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,162 +1,277 @@
-# 为 FastExcel 做贡献
+# Contribution Guidelines
-FastExcel 欢迎社区的每一位用户和开发者成为贡献者。无论是报告问题、改进文档、提交代码，还是提供技术支持，您的参与都将帮助 FastExcel
变得更好。
+Welcome every user and developer in the community to become contributors.
Whether it's reporting issues, improving
+documentation, submitting code, or providing technical support, your
participation will help make the Apache Fesod (
+Incubating) better.
---
-## 报告问题
+## Contribution Directions
-我们鼓励用户在使用 FastExcel 的过程中随时提供反馈。您可以通过 [NEW
ISSUE](https://github.com/fast-excel/fastexcel/issues/new/choose) 提交问题。
+There are many ways to contribute to Apache Fesod (Incubating):
-### 高质量问题报告
+- Fix typos
+- Fix bugs
+- Remove redundant code
+- Add test cases
+- Enhance functionality
+- Add comments to improve code readability
+- Optimize code structure
+- Improve or refine documentation
-为了提高沟通效率，请在提交问题前：
+**Principle**:
-1. **搜索现有问题**：检查您的问题是否已被报告。如果存在，请直接在现有问题下评论补充详细信息，而不是创建新问题。
-2. **使用问题模板**：问题模板位于 [ISSUE
TEMPLATE](./.github/ISSUE_TEMPLATE)，请按照模板要求填写，以确保问题描述准确且完整。
-
-以下情况适合提交新问题：
-
-- Bug 报告
-- 新功能需求
-- 性能问题
-- 功能提案或设计
-- 文档改进
-- 测试覆盖率优化
-- 需要技术支持
-- 其他与项目相关的问题
-
-> **注意**：请勿在问题中包含敏感信息，如密码、密钥、服务器地址或私人数据。
+- Any pull request that contributes to the improvement of the project should
be encouraged.
+- Before contributing a new feature, please propose and discuss it in an
`issue` or `discussion`. We will not merge
+ features that have not been discussed and confirmed.
---
-## 贡献代码与文档
+## Contributing Code
-所有对 FastExcel 的改进均可通过 Pull Request (PR) 实现。无论是修复 Bug、优化代码、增强功能，还是改进文档，都非常欢迎！
+All improvements can be implemented through Pull Request (PR). Before
submitting a Pull Request, please familiarise
+yourself with the following guidelines:
-### 您可以贡献的方向
+### Workspace Preparation
-- 修复错别字
-- 修复 Bug
-- 删除冗余代码
-- 添加测试用例
-- 增强功能
-- 添加注释以提升代码可读性
-- 优化代码结构
-- 改进或完善文档
+To develop Apache Fesod (Incubating), you need **Maven 3.9 or above** and
**JDK (Java Development Kit) 17 or above**.
+However, you must
+use **Java 1.8** compatible language features during compilation to ensure
Apache Fesod (Incubating) can run in
+environments with Java
+1.8 or above.
-**原则**：**任何有助于项目改进的 PR 都值得鼓励！**
+> You can use tools such as [SDKMAN](https://sdkman.io/) to configure multiple
versions of the Java toolchain.
-在提交 PR 前，请熟悉以下指南：
+### Fork the repository
-1. [工作区准备](#工作区准备)
-2. [分支定义](#分支定义)
-3. [提交规则](#提交规则)
-4. [PR 说明](#PR-说明)
+Ensure that you have registered a GitHub account and follow the steps below to
configure your local development
+environment:
----
+**Fork the repository**: Click the `Fork` button on the Apache Fesod (
+Incubating) [GitHub page](https://github.com/apache/fesod) to copy the project
to your GitHub account.
-### 工作区准备
+```bash
+https://github.com/<your-username>/fesod
+```
-开发 FastExcel 需要 **3.8.1及以上版本的Maven** 和 **17及以上版本的JDK (Java Development Kit)**
。目前，开发环境推荐 **3.9.0** 及以上版本的Maven和 **21** 及以上的版本Java，但在编译过程中必须使用 **Java 1.8**
兼容的语言特性，保证 FastExcel 能在 Java 1.8 及以上版本环境中运行。
+**Clone Repository**: Run the following command to clone the forked project to
your local machine:
-您可以使用 [SDKMAN](https://sdkman.io/) 等工具配置多版本的 Java 工具链。如果使用 IntelliJ IDEA
开发，可以设置项目 [Language
Level](https://www.jetbrains.com/help/idea/project-settings-and-structure.html#language-level)
为 8 以确保后向兼容。
+```bash
+git clone [email protected]:<your-username>/fesod.git
+```
-确保您已注册 GitHub 账号，并按照以下步骤完成本地开发环境配置：
+**Set Upstream Repository**: Set the official repository as `upstream` for
easy synchronization of updates:
-1. **Fork 仓库**：在 FastExcel 的 [GitHub
页面](https://github.com/fast-excel/fastexcel) 点击 `Fork` 按钮，将项目复制到您的 GitHub
账户下，例如：`https://github.com/<your-username>/fastexcel`。
-2. **克隆代码库**：运行以下命令将 Fork 的项目克隆到本地：
- ```bash
- git clone [email protected]:<your-username>/fastexcel.git
- ```
-3. **设置上游仓库**：将官方仓库设置为 `upstream`，方便同步更新：
- ```bash
- git remote add upstream [email protected]:fast-excel/fastexcel.git
- git remote set-url --push upstream no-pushing
- ```
- 运行 `git remote -v` 可检查配置是否正确。
+```bash
+git remote add upstream [email protected]:apahce/fesod.git
+git remote set-url --push upstream no-pushing
+```
----
+Running `git remote -v` can verify if the configuration is correct.
-### 分支定义
+### Branch definition
-在 FastExcel 中，所有贡献应基于 `main` 开发分支。此外，还有以下分支类型：
+In Apache Fesod (Incubating), all contributions should be based on the `main`
development branch. Additionally, there
+are the following branch types:
-- **release 分支**：用于版本发布（如 `0.6.0`, `0.6.1`）。
-- **feature 分支**：用于开发较大的功能。
-- **hotfix 分支**：用于修复重要 Bug。
+- **release branches**: Used for version releases (e.g., `1.1.0`, `1.1.1`).
+- **feature branches**: Used for developing major features.
+- **hotfix branches**: Used for fixing critical bugs.
-提交 PR 时，请确保变更基于 `main` 分支。
+When submitting a PR, please ensure that the changes are based on the `main`
branch.
----
+### Commit Rules
-### 提交规则
+#### Commit Message
-#### 提交信息
+Please ensure that commit messages are clear and descriptive, use **English**,
and do not exceed 100 characters.
-请确保提交消息清晰且具有描述性，遵循以下格式：
+The following types of commit messages are allowed and must follow the
following format:
-- **docs**: 更新文档，例如 `docs: 更新 PR 提交指南`。
-- **feature**: 新功能，例如 `feature: 支持 并发写入`。
-- **bugfix**: 修复 Bug，例如 `bugfix: 修复空指针异常`。
-- **refactor**: 重构代码，例如 `refactor: 优化数据处理逻辑`。
-- **test**: 增加或改进测试，例如 `test: 添加单元测试`。
+- **docs**: Update documentation, e.g., `docs: update README.md`
+- **feature/feat**: New features, e.g., `feature: support for xxx`
+- **bugfix/fix**: Bug fixes, e.g., `fix: fix NPE in the A class`
+- **refactor**: Code refactoring (no functional changes), e.g., `refactor:
optimise data processing logic`
+- **style**: Code formatting, e.g., `style: update code style`
+- **test**: Adding or improving tests, e.g., `test: add new test cases`
+- **chore**: Changes to the build process or auxiliary tools, e.g., `chore:
improve issue template`
+- **dependency**: Modifications to third-party dependency libraries, e.g.,
`dependency: upgrade poi version to 5.4.1`
-不建议使用模糊的提交信息，如：
+Avoid using vague commit messages like:
-- ~~修复问题~~
-- ~~更新代码~~
+- ~~fixed issue~~
+- ~~update code~~
-如果需要帮助，请参考 [如何编写 Git 提交消息](http://chris.beams.io/posts/git-commit/)。
+For assistance, refer to [How to Write a Git Commit
Message](http://chris.beams.io/posts/git-commit/).
-#### 提交内容
+#### Commit Content
-一次提交应包含完整且可审查的更改，确保：
+Each commit should contain complete and reviewable changes, ensuring:
-- 避免提交过于庞大的改动。
-- 每次提交内容独立且可通过 CI 测试。
+- Avoid committing overly large changes.
+- Each commit content is independent and can pass CI tests.
-另外，请确保提交时配置正确的 Git 用户信息：
+Also, ensure the correct Git user information is configured when committing:
```bash
git config --get user.name
git config --get user.email
```
+### PR Description
+
+To help reviewers quickly understand the content and purpose of the PR, use
+the
[pull_request_template](https://github.com/apache/fesod/blob/main/.github/pull_request_template.md).
A
+detailed description greatly improves code review efficiency.
+
---
-### PR 说明
+## Contribution of Test Cases
-为了帮助审阅者快速了解 PR 的内容和目的，请使用 [PR
模板](.github/pull_request_template.md)。详细的描述将极大提高代码审阅效率。
+Any contribution of test cases is encouraged, especially unit tests. It is
recommended to create `XXXTest.java` files in
+the corresponding module's `test` directory, preferably using the `JUnit5`
framework.
---
-## 测试用例贡献
+## Contribution Document
+
+Documentation is an important component of the Apache Fesod (Incubating)
official website and serves as a vital bridge
+between the
+project and the community.The Apache Fesod (Incubating) official website is
built
+using [Docusaurus](https://docusaurus.io/), and the
+documentation is maintained in the
[website](https://github.com/apache/fesod/tree/main/website) directory.
+
+### Requirements
+
+- [Node.js](https://nodejs.org/en/download/) version 18.0 or above (which can
be checked by running `node -v`). You can
+ use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions
on a single machine installed.
+- When installing Node.js, you are recommended to check all checkboxes related
to dependencies.
+
+### Directory Structure Description
+
+Docusaurus supports I18n. The main documentation directory structure that
needs to be maintained is as follows:
+
+```bash
+.
+├── community # Community(English)
+├── docs # Documentation(English)
+└── i18n # I18n
+ └── zh-cn
+ ├── docusaurus-plugin-content-docs
+ │ └── current # Documentation(Simplified Chinese)
+ └── docusaurus-plugin-content-docs-community
+ └── current # Community(Simplified Chinese)
+```
+
+The directory structure for single-language documents is as follows:
+
+```bash
+.
+├── quickstart # 1. Quick Start
+├── read # 2. Read
+├── write # 3. Write
+├── fill # 4. Fill
+├── community # 5. Community
+└── help # 6. FAQ
+```
+
+### Documentation Writing Guidelines
+
+- Use file paths with the `.md` extension
+
+```markdown
+[Example](docs/quickstart/example.md)
+```
+
+- Use paths relative to the docs/ directory
-任何测试用例的贡献都值得鼓励，尤其是单元测试。建议在对应模块的 `test` 目录中创建 `XXXTest.java` 文件，推荐使用 JUnit5 框架。
+```markdown
+[Example](docs/quickstart/example.md)
+```
+
+- Image files must be stored in the `static/img` directory and referenced
using relative directory paths.
+
+```markdown
+[img](/img/docs/fill/listFill_file.png)
+```
+
+### Preview and generate static files
+
+Enter the `website` directory and execute the command
+
+#### Installation
+
+```bash
+yarn install
+```
+
+#### Local Development
+
+```bash
+# English
+yarn start
+
+# Simplified Chinese
+yarn start --locale zh-cn
+```
+
+This command starts a local development server and opens up a browser window.
Most changes are reflected live without
+having to restart the server.
+
+> Only one language version can be run at a time.
+
+#### Build(Optional)
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be
served using any static contents hosting
+service.
+
+### Document Format Inspection
+
+Apache Fesod (Incubating) uses
[markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) to check
document
+formatting. After writing the relevant Markdown articles, you can run the
following command locally to pre-check whether
+the Markdown formatting meets the requirements:
+
+```bash
+cd website && yarn
+
+yarn md-lint
+
+# If the documentation is wrong, you can use the following command to attempt
an automatic repair.
+yarn md-lint-fix
+```
+
+- For formatting rules for Markdown articles you can refer
+ to:
[Markdown-lint-rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)
+- Markdown format configuration file in the
+ project:
[.markdownlint-cli2.jsonc](https://github.com/apache/fesod/blob/main/website/.markdownlint-cli2.jsonc)
---
-## 其他参与方式
+## Other Ways to Contribute
-除了直接贡献代码，以下方式同样是对 FastExcel 的宝贵支持：
+Apart from directly contributing code, the following ways are also valuable
support for Apache Fesod (Incubating):
-- 回答其他用户的问题。
-- 帮助审阅他人的 PR。
-- 提出改进建议。
-- 撰写技术博客，宣传 FastExcel。
-- 在社区中分享项目相关知识。
+- Answering other users' questions.
+- Assisting in reviewing others' PRs.
+- Providing improvement suggestions.
+- Writing technical blogs to promote.
+- Sharing project-related knowledge in the community.
---
-## 代码风格
+## Code Style
-FastExcel 使用 [Spotless](https://github.com/diffplug/spotless)
作为代码格式化工具。请确保在提交前运行以下命令以自动格式化代码：
+Apache Fesod (Incubating) uses
[Spotless](https://github.com/diffplug/spotless) as its code formatting tool.
Please
+ensure you run the following command to automatically format your code before
submitting:
-```shell
-./mvnw spotless:apply
+```bash
+mvn spotless:apply
```
---
-**最后，感谢您对 FastExcel 的支持！每一份帮助，都是我们前进的动力。**
+Finally, thank you for your support of Apache Fesod (Incubating)!
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
