Skip to content

docs: backport terminology corrections to 3.16 - #14120

Open
kayx23 wants to merge 1 commit into
apache:release/3.16from
kayx23:docs/backport-terminology-316
Open

kayx23 wants to merge 1 commit into
apache:release/3.16from
kayx23:docs/backport-terminology-316

Conversation

@kayx23

@kayx23 kayx23 commented Oct 28, 2026

Copy link
Copy Markdown
Member

Summary

  • port the corrected APISIX key-concept explanations into release/3.16
  • preserve useful examples, configuration tables, and English and Chinese coverage
  • retain only behavior verified in the 3.16 source
  • keep the terminology work separate from the version-specific Admin API contract in docs: add source-verified 3.16 Admin API contract #14082

Why these corrections are needed

  • Consumer: the previous page treated a Consumer ID as its runtime identity and showed an Upstream attached to a Consumer, although 3.16 identifies Consumers by username and has no Consumer Upstream.
  • Credential: each Credential contains at most one authentication plugin, while a Consumer can hold multiple Credentials for different plugins or the same plugin with distinct identifying values.
  • Plugin Metadata: shared logger log_format metadata has a defined fallback, but metadata does not have one universal precedence rule for every plugin and field.
  • Stream Route: 3.16 supports sni filtering but not the newer snis field, so this backport documents only sni.
  • Secret and router expressions: the existing text overstates plaintext protection and depends on API7-owned links and an iRESTY hostname.

Version-specific execution order

This backport deliberately does not copy the 3.17+ Global Rule phase-order correction. In 3.16, run_global_rules(..., nil) executes global rewrite and access handlers before local plugins run. The 3.16 page therefore keeps the branch-accurate global-first statement while adopting the corrected concept introduction.

Porting strategy

The detailed API7 APISIX key-concept pages were corrected and source-verified first. This PR adapts those corrections to the 3.16 source instead of copying newer branch behavior unchanged.

API7-hosted diagram assets are not embedded because the public Apache pages should not depend on API7 infrastructure. Their useful scenarios remain in prose. The removed Consumer diagram was technically inaccurate because it attached an Upstream to a Consumer.

The CI baseline #14095 is merged. #14082 should merge after this terminology PR so its contract links resolve to the corrected Apache pages.

Validation

  • one clean commit containing 11 Markdown files
  • markdownlint on every changed Markdown file
  • repository-wide internal link checker
  • Chinese line-segmentation checker
  • git diff --check origin/release/3.16...HEAD
  • verified that the corrected scope introduces no API7 repository, CDN, or iRESTY dependencies
  • source audit against 3.16 schemas, Admin API handlers, Credential behavior, shared logger metadata handling, stream-route fields, and Global Rule execution paths

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant