Skip to content

Commit c57f58b

Browse files
deleipsxjoy
delei
and
psxjoy
authored
docs: initialise English version (#474)
Co-authored-by: Shuxin Pan <[email protected]>
1 parent a9bd19e commit c57f58b

34 files changed

+3908
-204
lines changed

‎docs/en-US/community/bug-report.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Feedback
2+
3+
We appreciate all the feedback and suggestions you have. If you find any bugs during use, you can submit the issue through the [NEW ISSUE](https://github.com/fast-excel/fastexcel/issues/new/choose) page.
4+
5+
## Before Submitting
6+
7+
Before creating a new issue, please ensure you have completed the following preparatory steps. This will help avoid duplicate work and save both your time and the maintainers' time.
8+
9+
### Read the Documentation
10+
- Please read the `README` file and the official documentation in the project to see if there are any solutions to the problems mentioned.
11+
12+
### Search Existing Issues
13+
14+
- Visit the [Issue List](https://github.com/fast-excel/fastexcel/issues) and search for keywords.
15+
- If you find a similar issue, please **comment and provide additional details** under that issue instead of creating a new one.
16+
- If an unresolved issue is closed for some reason, please **comment and provide additional details** to reopen it.
17+
18+
### Update to the latest version
19+
Please make sure you are using the latest stable version of the project or the latest code from the main branch. Many issues have been resolved in newer versions.
20+
21+
---
22+
23+
## Creating a New Issue
24+
25+
If you confirm that your issue has not been reported, please submit a new issue through the [NEW ISSUE](https://github.com/fast-excel/fastexcel/issues/new/choose) page.
26+
27+
**Please use the issue template** and provide as much information as possible, such as:
28+
29+
- Environment information (operating system, version used, etc.).
30+
- Steps to reproduce the issue.
31+
- Error logs or screenshots.
32+
- Provide a minimal reproducible example.
33+
34+
The following situations are appropriate for submitting a new issue:
35+
36+
- Bug reports
37+
- New feature
38+
- Performance issues
39+
- Function proposals or design suggestions
40+
- Documentation improvements
41+
- Optimization of test coverage
42+
- Need for technical support
43+
- Other issues related to the project
44+
45+
---
46+
47+
## Notes
48+
49+
- The title of the issue should be clear and concise, and should be no longer than 50 characters.
50+
- Please use polite language in the issue description and content.
51+
- Each issue should focus on a single topic, please do not combine multiple issues into one.
52+
- Unless a specific developer has been explicitly assigned to the issue in advance, please do not arbitrarily assign it to a particular developer.
53+
- Do not include sensitive information such as passwords, keys, server addresses, or private data in the issue.
54+
55+
Thank you for contributing to the improvement of the project! Every feedback you provide is the driving force behind our progress.

‎docs/en-US/community/contact.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Contact Us
2+
3+
We appreciate all the feedback and opinions you have. If you need any help or have any suggestions during use, please feel free to contact us!
4+
5+
## Issues
6+
7+
All issues will be tracked and handled through [GitHub Issues](https://github.com/fast-excel/fastexcel/issues).
8+
9+
## Discussions
10+
11+
For development discussions and user exchanges, please use [GitHub Discussions](https://github.com/fast-excel/fastexcel/discussions).
12+
13+
## WeChat Public
14+
15+
Follow the author "Programmer Xiao Lan" on WeChat to join the technical discussion group and access more technical insights and the latest updates.
16+
17+
![img](../../images/wechat-public.jpg)

‎docs/en-US/community/contribution.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Contribution Guidelines
2+
3+
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 FastExcel better.
4+
5+
---
6+
7+
## Contribution Directions
8+
9+
There are many ways to contribute to FastExcel:
10+
11+
- Fix typos
12+
- Fix bugs
13+
- Remove redundant code
14+
- Add test cases
15+
- Enhance functionality
16+
- Add comments to improve code readability
17+
- Optimize code structure
18+
- Improve or refine documentation
19+
20+
**Principle**:
21+
- Any pull request that contributes to the improvement of the project should be encouraged.
22+
- 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.
23+
24+
---
25+
26+
## Contributing Code
27+
28+
All improvements can be implemented through Pull Request (PR). Before submitting a Pull Request, please familiarise yourself with the following guidelines:
29+
30+
### Workspace Preparation
31+
32+
Developing FastExcel requires **Maven 3.8** and **JDK (Java Development Kit)**. Currently, the development environment requires **Java 21** or higher, but during compilation, you must use language features compatible with **Java 1.8** to ensure that FastExcel can run in Java 1.8 or higher environments.
33+
34+
> You can use tools such as [SDKMAN](https://sdkman.io/) to configure multiple versions of the Java toolchain.
35+
36+
### Fork the repository
37+
38+
Ensure that you have registered a GitHub account and follow the steps below to configure your local development environment:
39+
40+
**Fork the repository**: Click the `Fork` button on the FastExcel [GitHub page](https://github.com/fast-excel/fastexcel) to copy the project to your GitHub account.
41+
42+
```
43+
https://github.com/<your-username>/fastexcel
44+
```
45+
46+
**Clone Repository**: Run the following command to clone the forked project to your local machine:
47+
```bash
48+
git clone [email protected]:<your-username>/fastexcel.git
49+
```
50+
51+
**Set Upstream Repository**: Set the official repository as `upstream` for easy synchronization of updates:
52+
```bash
53+
git remote add upstream [email protected]:fast-excel/fastexcel.git
54+
git remote set-url --push upstream no-pushing
55+
```
56+
57+
Running `git remote -v` can verify if the configuration is correct.
58+
59+
60+
### Branch definition
61+
62+
In FastExcel, all contributions should be based on the `main` development branch. Additionally, there are the following branch types:
63+
64+
- **release branches**: Used for version releases (e.g., `1.1.0`, `1.1.1`).
65+
- **feature branches**: Used for developing major features.
66+
- **hotfix branches**: Used for fixing critical bugs.
67+
68+
When submitting a PR, please ensure that the changes are based on the `main` branch.
69+
70+
### Commit Rules
71+
72+
#### Commit Message
73+
74+
Please ensure that commit messages are clear and descriptive, use **English**, and do not exceed 100 characters.
75+
76+
The following types of commit messages are allowed and must follow the following format:
77+
78+
- **docs**: Update documentation, e.g., `docs: update README.md`
79+
- **feature/feat**: New features, e.g., `feature: support for xxx`
80+
- **bugfix/fix**: Bug fixes, e.g., `fix: fix NPE in the A class`
81+
- **refactor**: Code refactoring (no functional changes), e.g., `refactor: optimise data processing logic`
82+
- **style**: Code formatting, e.g., `style: update code style`
83+
- **test**: Adding or improving tests, e.g., `test: add new test cases`
84+
- **chore**: Changes to the build process or auxiliary tools, e.g., `chore: improve issue template`
85+
- **dependency**: Modifications to third-party dependency libraries, e.g., `dependency: upgrade poi version to 5.4.1`
86+
87+
Avoid using vague commit messages like:
88+
89+
- ~~fixed issue~~
90+
- ~~update code~~
91+
92+
For assistance, refer to [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
93+
94+
#### Commit Content
95+
96+
Each commit should contain complete and reviewable changes, ensuring:
97+
98+
- Avoid committing overly large changes.
99+
- Each commit content is independent and can pass CI tests.
100+
101+
Also, ensure the correct Git user information is configured when committing:
102+
103+
```bash
104+
git config --get user.name
105+
git config --get user.email
106+
```
107+
108+
### PR Description
109+
110+
To help reviewers quickly understand the content and purpose of the PR, use the [PR 模板](https://github.com/fast-excel/fastexcel/blob/main/.github/pull_request_template.md). A detailed description greatly improves code review efficiency.
111+
112+
---
113+
114+
## Contribution of Test Cases
115+
116+
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.
117+
118+
---
119+
120+
## Contribution Document
121+
122+
Documentation is an important component of the FastExcel official website and serves as a vital bridge between the project and the community.
123+
124+
### Directory Structure Description
125+
126+
```bash
127+
.
128+
├── quickstart # 1. Quick Start
129+
├── read # 2. Read
130+
├── write # 3. Write
131+
├── fill # 4. Fill
132+
├── community # 5. Community
133+
└── help # 6. FAQ
134+
```
135+
136+
### Documentation Writing Guidelines
137+
138+
- Use file paths with the `.md` extension
139+
``` markdown
140+
[Example](quickstart/example.md)
141+
```
142+
143+
- Use paths relative to the docs/ directory
144+
``` markdown
145+
[Example](quickstart/example.md)
146+
```
147+
148+
- Image files must be stored in the `docs/images` directory and referenced using relative directory paths.
149+
``` markdown
150+
[img](../../images/fill/listFill_file.png)
151+
```
152+
153+
---
154+
155+
## Other Ways to Contribute
156+
157+
Apart from directly contributing code, the following ways are also valuable support for FastExcel:
158+
159+
- Answering other users' questions.
160+
- Assisting in reviewing others' PRs.
161+
- Providing improvement suggestions.
162+
- Writing technical blogs to promote FastExcel.
163+
- Sharing project-related knowledge in the community.
164+
165+
---
166+
167+
## Code Style
168+
169+
FastExcel 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:
170+
171+
```bash
172+
mvn spotless:apply
173+
```
174+
175+
---
176+
177+
Finally, thank you for your support of FastExcel!

‎docs/en-US/community/development.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Run or Build
2+
3+
This section explains how to build FastExcel from source code.
4+
5+
## Development environment
6+
7+
Developing FastExcel requires **Maven 3.8** and **JDK (Java Development Kit)**. Currently, the development environment requires **Java 21** or higher, but during compilation, you must use language features compatible with **Java 1.8** to ensure that FastExcel can run in Java 1.8 or higher environments.
8+
9+
> You can use tools such as [SDKMAN](https://sdkman.io/) to configure multiple versions of the Java toolchain.
10+
11+
## IDEA Settings
12+
13+
The following guidelines are for development using `IntelliJ IDEA`. Other versions may have some minor differences. Please follow all steps carefully.
14+
15+
### Project Settings
16+
17+
Set the project [Language Level](https://www.jetbrains.com/help/idea/project-settings-and-structure.html#language-level) to `8` to ensure backward compatibility.
18+
19+
## Git Usage
20+
21+
Ensure that you have registered a GitHub account and follow the steps below to configure your local development environment:
22+
23+
**Fork the repository**: Click the `Fork` button on the FastExcel [GitHub page](https://github.com/fast-excel/fastexcel) to copy the project to your GitHub account.
24+
25+
```
26+
https://github.com/<your-username>/fastexcel
27+
```
28+
29+
**Clone Repository**: Run the following command to clone the forked project to your local machine:
30+
```bash
31+
git clone [email protected]:<your-username>/fastexcel.git
32+
```
33+
34+
**Set Upstream Repository**: Set the official repository as `upstream` for easy synchronization of updates:
35+
```bash
36+
git remote add upstream [email protected]:fast-excel/fastexcel.git
37+
git remote set-url --push upstream no-pushing
38+
```
39+
40+
Running `git remote -v` can verify if the configuration is correct.
41+
42+
## Compilation
43+
44+
Run the following command to compile
45+
```bash
46+
mvn clean install -DskipTests
47+
```
48+
49+
To speed up the build process, you can:
50+
- Use `-DskipTests` to skip unit tests
51+
- Use Maven's parallel build feature, e.g., `mvn clean install -DskipTests -T 1C`
52+
53+
## Code Style
54+
55+
FastExcel 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:
56+
57+
```bash
58+
mvn spotless:apply
59+
```

0 commit comments

Comments
 (0)