DanielCarter-stack commented on PR #10420:
URL: https://github.com/apache/seatunnel/pull/10420#issuecomment-3832874533
<!-- code-pr-reviewer -->
<!-- cpr:pr_reply_v2_parts {"group": "apache/seatunnel#10420", "part": 1,
"total": 1} -->
### Issue 1: incompatible-changes.md missing from sidebar navigation
**Location**: `docs/sidebars.js:45` (exists in dev branch, deleted in HEAD)
**Related context**:
- File location: `docs/en/introduction/concepts/incompatible-changes.md`
- Original sidebar configuration:
`"introduction/concepts/incompatible-changes"`
- Sidebar configuration change: Deleted in commit `ec0188d17`
**Problem description**:
The `incompatible-changes.md` file documents breaking changes between
SeaTunnel versions and is **must-read** documentation for users before
upgrading. Although the file itself still exists, its navigation reference was
deleted in `sidebars.js`, preventing users from finding this document through
the documentation website's sidebar.
**Document content**:
This document contains the following key information:
- **API Changes**: Engine REST API table-level metric key format changes
(affects Grafana, Prometheus integration)
- **Transform Changes**:
- DataValidator `table_id` format changes
- SQL Transform datetime function behavior changes
**Potential risks**:
- **Risk 1**: Users are unaware of breaking changes when upgrading versions,
which may cause production environment failures
- **Risk 2**: Monitoring dashboards and alert rules that depend on old
metric keys become invalid, but users don't know they need to update them
- **Risk 3**: SQL query result changes (datetime function behavior changes),
leading to data errors
**Impact scope**:
- **Direct impact**: All users upgrading SeaTunnel versions
- **Indirect impact**:
- Grafana dashboard configurations need to be updated
- Prometheus alert rules need to be modified
- Jobs using DataValidator and SQL Transform may be affected
- **Impact surface**: Core documentation/all upgrading users
**Severity**: **CRITICAL**
**Improvement suggestions**:
```javascript
// docs/sidebars.js - should be kept in Introduction > Concepts category
{
"type": "category",
"label": "Concepts",
"items": [
"introduction/concepts/config",
"introduction/concepts/connector-v2-features",
"introduction/concepts/schema-feature",
"introduction/concepts/incompatible-changes" // Must keep
]
}
```
**Rationale**:
- This document is mandatory reading before upgrading and should be placed
in a prominent position
- Even if the documentation structure is adjusted, the navigation entry for
this document should not be removed
- Recommend keeping it under Concepts, or moving it to the top level of
Introduction
---
### Issue 2: Lack of documentation structure change description and
migration guide
**Location**: PR description, docs/en/introduction/about.md
**Problem description**:
This PR reorganizes the documentation structure, but provides no change
description, so users don't know:
- Which documents have been moved
- How to handle old links
- How to find the moved documents
**Potential risks**:
- **Risk 1**: Users' bookmarks become invalid and they cannot find the new
location
- **Risk 2**: Links in external tutorials and blogs become invalid
- **Risk 3**: Search engine indexes become invalid, affecting documentation
discoverability
**Impact scope**:
- **Direct impact**: All users viewing documentation
- **Indirect impact**: Third-party content referencing SeaTunnel
documentation
- **Impact surface**: Overall documentation usability
**Severity**: **MAJOR**
**Improvement suggestions**:
1. **Add change description in `docs/en/introduction/about.md`**:
```markdown
## Document Structure Updates
### January 2026
The documentation structure has been reorganized for better clarity:
- Configuration-related docs moved to `introduction/configuration/`
- Connector-specific docs moved to `connectors/`
- Engine-specific docs moved to `engines/`
If you're looking for a document that was previously in
`introduction/concepts/`, please check:
- [Configuration](../introduction/configuration/)
- [Connectors](../connectors/)
- [Engines](../engines/)
```
2. **Create redirect pages for old paths** (if deployment supports):
```markdown
---
redirect: ../configuration/JobEnvConfig
---
```
3. **Add change checklist in PR description**:
```markdown
### Document Structure Changes
- Moved `introduction/concepts/JobEnvConfig.md` →
`introduction/configuration/JobEnvConfig.md`
- Moved `introduction/concepts/connector-isolated-dependency.md` →
`connectors/connector-isolated-dependency.md`
- Moved `introduction/concepts/event-listener.md` →
`engines/event-listener.md`
- ... (完整列表)
```
**Rationale**:
- Improve user experience and reduce confusion
- Lower migration costs
- Demonstrate respect for users
---
### Issue 3: External link compatibility issues
**Location**: All moved documents
**Problem description**:
After documents are moved, all external links pointing to old paths will
become invalid, including:
- Internal cross-references in official documentation (although updated,
there may be omissions)
- Third-party tutorials, blogs
- User bookmarks
- Search engine indexes
**Potential risks**:
- **Risk 1**: Users get 404 errors when accessing through old links
- **Risk 2**: Reduced documentation accessibility and user satisfaction
- **Risk 3**: Affects SeaTunnel's professional image
**Impact scope**:
- **Direct impact**: All users accessing documentation through links
- **Indirect impact**: Third-party content referencing documentation
- **Impact surface**: Documentation ecosystem
**Severity**: **MAJOR**
**Improvement suggestions**:
1. **Configure HTTP redirect rules** (in documentation deployment
configuration):
```yaml
# For example in docusaurus.config.js or Web server configuration
redirects:
- from: /docs/en/introduction/concepts/JobEnvConfig
to: /docs/en/introduction/configuration/JobEnvConfig
- from: /docs/en/introduction/concepts/connector-isolated-dependency
to: /docs/en/connectors/connector-isolated-dependency
# ... all other moved documents
```
2. **Create redirect documents** (if server redirects cannot be configured):
```markdown
---
title: JobEnvConfig
---
# Document Moved
This document has been moved to
[JobEnvConfig](../introduction/configuration/JobEnvConfig.md).
Please update your bookmarks.
```
**Rationale**:
- Ensure backward compatibility
- Improve user experience
- Align with Web best practices
---
### Issue 4: Insufficient PR description information
**Location**: PR description
**Problem description**:
The PR description is too simple and does not provide:
- Specific change checklist
- Explanation of change reasons
- Explanation of relationship with PR #10262
- Key points for review
**Potential risks**:
- **Risk 1**: Reviewers find it difficult to understand the complete scope
of the PR
- **Risk 2**: Difficult to trace change history after merging
- **Risk 3**: Other contributors cannot understand the evolution of
documentation structure
**Impact scope**:
- **Direct impact**: PR review process
- **Indirect impact**: Project maintenance and knowledge transfer
- **Impact surface**: Collaboration efficiency
**Severity**: **MINOR**
**Improvement suggestions**:
```markdown
### Purpose of this pull request
This is a follow-up to PR #10262 to further optimize the document structure.
### Changes Made
1. **Created new `configuration` directory** under `introduction/`
- Moved 7 configuration-related docs from `concepts/` to `configuration/`
- Updated internal cross-references
2. **Reorganized topic-specific docs**
- `connector-isolated-dependency.md` → `connectors/`
- `event-listener.md` → `engines/`
3. **Updated navigation**
- Added `Configuration` category in sidebar
- Simplified `Concepts` category
- Moved docs to appropriate categories
### File Movement List
See the diff for complete list of moved files.
### Related PRs
- #10262: Initial document structure optimization
- #10351: Previous doc structure adjustment
### Breaking Changes
- External links to moved docs will break (need redirects)
- Users' bookmarks may need updating
```
**Rationale**:
- Improve review efficiency
- Facilitate tracing change history
- Demonstrate professionalism
---
--
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]
