Skip to content

[improve] repair doc dead link and error link#10439

Open
misi1987107 wants to merge 1 commit intoapache:devfrom
misi1987107:feature-repair-doc-link
Open

[improve] repair doc dead link and error link#10439
misi1987107 wants to merge 1 commit intoapache:devfrom
misi1987107:feature-repair-doc-link

Conversation

@misi1987107
Copy link
Contributor

Purpose of this pull request

Fix doc dead links and error links

Does this PR introduce any user-facing change?

How was this patch tested?

Check list

@DanielCarter-stack
Copy link

DanielCarter-stack commented Feb 3, 2026

Issue 1: Root directory README.md not updated

Location: /README.md:未修改

当前内容:
- [Source Connectors](https://seatunnel.apache.org/docs/connector-v2/source)
- [Sink Connectors](https://seatunnel.apache.org/docs/connector-v2/sink)
- [Transform Connectors](docs/en/transform-v2)
- [SeaTunnel Zeta Engine](https://seatunnel.apache.org/docs/start-v2/locally/quick-start-seatunnel-engine/)

相关上下文:
- PR 范围:仅修改了 docs/ 目录下的文件
- 根目录 README.md:未被包含在此 PR 中

Problem Description:
The root directory's README.md file still contains links pointing to the old documentation structure. Although this PR's scope is clearly limited to the docs/ directory, README.md is the project's facade, and containing old links affects user experience.

Potential Risks:

  • Users clicking links from the GitHub repository homepage will encounter 404 errors
  • Causes confusion for new users and reduces the project's professional image
  • Search engines may index incorrect links

Scope of Impact:

  • Direct impact: All users accessing the GitHub repository homepage
  • Indirect impact: Project's online image and user experience
  • Impact scope: Project level (not specific to Connectors)

Severity: MINOR

Improvement Suggestions:
Create a separate PR or supplement modifications to README.md in this PR:

# Suggested changes
- [Source Connectors](https://seatunnel.apache.org/docs/connectors/source)
- [Sink Connectors](https://seatunnel.apache.org/docs/connectors/sink)
- [Transform Connectors](docs/en/transforms)
- [SeaTunnel Zeta Engine](https://seatunnel.apache.org/docs/getting-started/locally/quick-start-seatunnel-engine)

Rationale: Maintain consistency between the project homepage and documentation structure, ensuring users can access correct documentation from any entry point.


Issue 2: Lack of automated documentation link checking

Location: CI/CD configuration (not involved in this PR)

Problem Description:
As seen in git log, there have been multiple previous commits regarding dead link fixes (#9023, #8525, #8510, #8251), indicating that dead links are an ongoing issue. Currently, there is no automated documentation link checking mechanism.

Potential Risks:

  • Future documentation restructuring or renaming may introduce dead links again
  • Manual checking of all links is inefficient and prone to omissions
  • Link issues cannot be automatically detected during code merging

Scope of Impact:

  • Direct impact: Documentation maintenance efficiency
  • Indirect impact: User experience and project professionalism
  • Impact scope: Overall documentation quality

Severity: MINOR

Improvement Suggestions:
It is recommended to add a documentation link checking step in CI (can be implemented in a separate PR):

# Sample GitHub Actions configuration
- name: Check Markdown Links
  run: |
    npm install -g markdown-link-check
    find docs/ -name "*.md" -exec markdown-link-check {} \;

Rationale: Prevent dead link issues from recurring and improve documentation quality assurance.


Issue 3: PR description lacks change details

Location: PR description template

Problem Description:
The "Does this PR introduce any user-facing change?" and "How was this patch tested?" sections in the PR description are filled with "No" or left blank. For documentation fix PRs, more detailed explanations should be provided.

Potential Risks:

  • Reviewers find it difficult to quickly understand the scope and impact of changes
  • Users cannot obtain useful change information from the PR description
  • Does not comply with Apache project submission guidelines

Scope of Impact:

  • Direct impact: PR review efficiency
  • Indirect impact: Change tracking and traceability
  • Impact scope: Project collaboration quality

Severity: MINOR

Improvement Suggestions:
Improve the PR description template:

### Does this PR introduce any user-facing change?
Yes. This PR fixes dead links in documentation. Previously, users clicking on links like
[exactly-once](../../concept/connector-v2-features.md) would encounter 404 errors.
After this change, all links point to the correct new documentation structure.

### How was this patch tested?
1. Verified all new file paths exist using shell commands
2. Spot-checked multiple modified files to confirm link correctness
3. Ensured link count balance (120 removed, 120 added)
4. Verified anchors (like #schema_save_mode-enum) exist in target files

Rationale: Improve PR transparency and reviewability, aligning with open source project best practices.


Issue 4: Some files may have been missed

Location: Some files in docs/en/connectors/sink/ and docs/zh/connectors/sink/

Problem Description:
Through the find command, it was discovered that some sink files are still not included in the modification list (such as Console.md, Greenplum.md, etc.). It needs to be confirmed whether these files contain old links.

Potential Risks:

  • If these files contain old links but are not fixed, users will still encounter dead links
  • Incomplete fix

Scope of Impact:

  • Direct impact: Users accessing documentation for unrestored connectors
  • Impact scope: Specific Connectors

Severity: MINOR (verification required)

Improvement Suggestions:
Verify whether the following files contain old links:

grep -r "connector-v2\|concept/\|transform-v2\|seatunnel-engine" \
  docs/en/connectors/sink/{Console,Greenplum, DingTalk, SftpFile}.md \
  docs/zh/connectors/sink/{Console,Greenplum, DingTalk, SftpFile}.md

If old links are found, they should be supplemented and fixed in a subsequent PR.

Rationale: Ensure the integrity and consistency of documentation fixes.


Copy link
Contributor

@davidzollo davidzollo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1
LGTM

@zhangshenghang
Copy link
Member

Can you turn on the CI for detecting dead links? Let's run this CI for a while recently.

@corgy-w
Copy link
Contributor

corgy-w commented Feb 4, 2026

Can you turn on the CI for detecting dead links? Let's run this CI for a while recently.

@misi1987107 +1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants