GOODBOY008 opened a new issue, #725:
URL: https://github.com/apache/fesod/issues/725
# Fesod Examples Module Refactoring Proposal
## 1. Executive Summary
This proposal outlines a plan to refactor the `fesod-examples` module by:
1. Moving example code from `src/test/java` to `src/main/java` (following
Apache Spark/Flink patterns)
2. Cleaning up temporary/issue-specific test classes
3. Establishing clear guidelines for example code organization
## 2. Background & Motivation
### 2.1 Current State
The `fesod-examples` module currently contains all code under
`src/test/java`:
```
fesod-examples/src/test/java/org/apache/fesod/sheet/
├── demo/ # Well-structured examples for documentation
│ ├── fill/ # 2 files - Fill functionality examples
│ ├── migration/ # Empty
│ ├── rare/ # 1 file - Rare use cases
│ ├── read/ # 23 files - Read examples with data classes & listeners
│ ├── web/ # 6 files - Spring Boot web integration examples
│ └── write/ # 19 files - Write examples with handlers & styles
├── temp/ # Temporary/experimental tests (~70+ files)
│ ├── bug/ # Bug reproduction tests
│ ├── cache/ # Cache related tests
│ ├── csv/ # CSV format tests
│ ├── issue1662/ # Issue-specific tests
│ ├── issue1663/ # Issue-specific tests
│ ├── issue2319/ # Issue-specific tests
│ ├── issue2443/ # Issue-specific tests
│ ├── issue406/ # Issue-specific tests
│ ├── poi/ # POI compatibility tests
│ ├── large/ # Large file tests
│ └── ... # Other experimental/temp tests
└── util/ # 2 files - Test utilities
```
### 2.2 Industry Best Practices
**Apache Spark Examples Module:**
- Examples are in `src/main/java` as runnable programs
- Package: `org.apache.spark.examples.*`
- Each example has a `main()` method
- Used for documentation and user learning
- Tests are separate integration tests
**Apache Flink Examples Module:**
- Examples are in `src/main/java`
- Package: `org.apache.flink.streaming.examples.*`
- Examples are actual runnable programs
- Integration tests validate examples via `src/test/java`
## 3. Proposed Changes
### 3.1 Phase 1: Restructure to Production Layout
**Move demo examples to `src/main/java`:**
```
fesod-examples/src/main/java/org/apache/fesod/sheet/examples/
├── read/
│ ├── SimpleReadExample.java # Basic reading
│ ├── ConverterReadExample.java # Custom converters
│ ├── IndexOrNameReadExample.java # Column mapping
│ ├── NoModelReadExample.java # Map-based reading
│ ├── ExtraDataReadExample.java # Comments/hyperlinks
│ └── data/ # Data classes
│ ├── DemoData.java
│ └── ...
├── write/
│ ├── SimpleWriteExample.java # Basic writing
│ ├── StyleWriteExample.java # Custom styles
│ ├── ImageWriteExample.java # Image handling
│ ├── MergeWriteExample.java # Cell merging
│ └── data/ # Data classes
│ ├── DemoData.java
│ └── ...
├── fill/
│ ├── SimpleFillExample.java # Template filling
│ └── data/
│ └── FillData.java
└── web/
├── WebExcelExample.java # Spring Boot integration
└── data/
├── DownloadData.java
└── UploadData.java
```
**Keep integration tests in `src/test/java`:**
```
fesod-examples/src/test/java/org/apache/fesod/sheet/examples/
├── ReadExamplesIT.java # Integration tests for read examples
├── WriteExamplesIT.java # Integration tests for write examples
├── FillExamplesIT.java # Integration tests for fill examples
└── WebExamplesIT.java # Integration tests for web examples
```
### 3.2 Phase 2: Handle Temp Directory Classes
**Remove all classes in the `temp/` directory** as they are:
- Bug reproduction tests for already-fixed issues
- Issue-specific tests no longer relevant
- Experimental code not part of standard examples
- Cluttering the codebase and making maintenance harder
These should be either:
1. **Migrated to fesod core unit tests** if they validate important
functionality
2. **Removed completely** if they are duplicates or no longer relevant
## 4. Benefits
1. **Alignment with Apache Standards**: Follows established patterns from
Apache Spark and Flink
2. **Clearer Intent**: Production examples are in `src/main/java`, test code
is in `src/test/java`
3. **Better Distribution**: Examples become part of released artifacts for
end users
4. **Improved Maintainability**: Removes accumulated temporary test code
5. **Better Documentation**: Examples serve as runnable documentation
6. **Clear Separation**: Example code and test code have distinct purposes
## 5. Implementation Plan
### Phase 1: Move demo examples
- [ ] Create new directory structure under `src/main/java`
- [ ] Move demo example files from `src/test/java/demo/*` to
`src/main/java/examples/*`
- [ ] Move supporting data classes
- [ ] Update package names to `org.apache.fesod.sheet.examples.*`
### Phase 2: Create integration tests
- [ ] Create integration test classes in `src/test/java`
- [ ] Write IT tests that verify each example executes correctly
- [ ] Ensure tests validate example outputs
### Phase 3: Clean up temp directory
- [ ] Review all files in `temp/` directory
- [ ] Migrate critical test cases to fesod core if needed
- [ ] Delete remaining temporary/issue-specific tests
- [ ] Update CI/CD if necessary
### Phase 4: Update documentation
- [ ] Update README with new example locations
- [ ] Update user guide to reference examples from `src/main/java`
- [ ] Generate example documentation from source code
## 6. Scope & Out of Scope
**In Scope:**
- Moving demo examples to production layout
- Removing temp directory
- Creating integration tests
- Documentation updates
**Out of Scope:**
- Changing example functionality
- Creating new examples (separate issue)
- Modifying core fesod library
## 7. Discussion Points
- Should all examples have a `main()` method for standalone execution?
- What's the minimum set of integration tests needed?
- Should we create a separate documentation module that generates from
examples?
- Timeline for implementation?
Related to: Apache Incubator project structure best practices
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
