Skip to content

docs(changelog): apply v3.x audit revisions across all 21 release sections#13362

Open
membphis wants to merge 2 commits into
masterfrom
docs/changelog-audit-v3.x-bulk
Open

docs(changelog): apply v3.x audit revisions across all 21 release sections#13362
membphis wants to merge 2 commits into
masterfrom
docs/changelog-audit-v3.x-bulk

Conversation

@membphis
Copy link
Copy Markdown
Member

Description

Follow-up to #13360 (typos / heading levels — merged) and tracked in #13359 (full audit). This PR applies the remaining audit findings to every v3.x release section in CHANGELOG.md:

  • Backfill the four patch sections (3.2.2 / 3.4.1 / 3.8.1 / 3.9.1) that exist on release/3.x branches but were never cherry-picked back to master.
  • Replace the 3.2.1 placeholder paragraph with the 5–6 real bugfixes from release/3.2.
  • Expand "implementation-side" wording to "user-side" for entries whose impact users can't read off the current text (OpenTelemetry span name, hmac-auth field rename, ssl_trusted_certificate default, lua-resty-session 4.x default, strict schema scope, etc.).
  • Move mis-classified breaking changes from Bugfixes → Change and add :warning:.
  • Add user-visible PRs that were previously omitted (10 in 3.13.0, ~17 in 3.2.0, etc.).
  • Deduplicate entries listed in two subsections of the same release (3.12.0, 3.10.0).
  • Add ### Security subsections to patch sections carrying jwt-auth bypass fix: upgrade api7-lua-resty-jwt to 0.2.5 #9837 / forward-auth POST header leak fix: add post request headers only if auth request method is post #11184.

Diff: +240 / −77 (net +163), all in CHANGELOG.md. No code changes.

Highlights by impact

Severity Item
⚠️⚠️ 3.15.0 #12862lua-resty-session 4.1.5 default = AES-256-GCM. Session cookies issued by ≤3.14.x will no longer decode after upgrade; all OIDC users will be forced to re-authenticate.
⚠️⚠️ Patch backfills 3.2.2 / 3.4.1 / 3.8.1 / 3.9.1 (incl. jwt-auth auth bypass #9837 and forward-auth POST header leak #11184 under ### Security) — these never reached master CHANGELOG users on the 3.x line.
⚠️ 3.14.0 #12551 X-Forwarded-* trusted-source change moved Bugfixes → Change with upgrade hint for trusted_addresses.
⚠️ 3.12.0 #11993 ssl_trusted_certificate default = system — outbound TLS calls (OIDC, loggers) may newly fail handshake; wording expanded.
⚠️ 3.11.0 #11601 credential resource silently dropped auth check + injects 3 upstream headers — promoted to Change with :warning:.
⚠️ 3.11.0 #11581 hmac-auth field rename (access_keykey_id), header consolidation, 4 fields removed — full breaking-change description added.
⚠️ 3.10.0 #11343 / #11312 config-default.yaml removed + lyaml stricter — promoted to :warning:.
⚠️ 3.7.0 #10393 OTel span name {method} {route} — tracing dashboards relying on URI-style names break.
⚠️ 3.6.0 #10233 strict schema — listed every affected resource (route / service / upstream / consumer / ssl / plugin_config / global_rule / stream_route / proto).

Verification

$ git diff --stat CHANGELOG.md
 CHANGELOG.md | 316 +++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 239 insertions(+), 77 deletions(-)

$ grep -cE "^- " CHANGELOG.md  # bullet count
1293   (was 1186; +107 new user-facing entries)

$ grep -nE "^## " CHANGELOG.md | head -25  # all 21 v3.x headers present, in order
24:## Table of Contents
91:## 3.16.0
143:## 3.15.0
206:## 3.14.1
221:## 3.14.0
323:## 3.13.0
414:## 3.12.0
488:## 3.11.0
519:## 3.10.0
576:## 3.9.1    <- backfilled
582:## 3.9.0
641:## 3.8.1    <- backfilled
647:## 3.8.0
694:## 3.7.0
736:## 3.6.0
770:## 3.5.0
825:## 3.4.1    <- backfilled
833:## 3.4.0
870:## 3.3.0
912:## 3.2.2    <- backfilled
946:## 3.2.1    <- placeholder replaced
961:## 3.2.0
1024:## 3.1.0
1080:## 3.0.0

All PR numbers added by this change were resolved against the live API to confirm they're real PRs (not issue numbers or typos).

Deliberately out of scope

Process improvements (separate effort)

The audit also recommends 6 release-process gates (rockspec diff gate, patch-CHANGELOG cherry-pick rule, breaking-change schema scan, PR-number cross-check, markdown lint, ### Security convention) to keep this pattern from recurring. Those will land separately in .github/workflows/.

Refs #13359.

Checklist

  • I have explained the need for this PR and the problem it solves
  • I have explained the changes or the new features added to this PR
  • I have added tests corresponding to the changes introduced in this PR (N/A — CHANGELOG-only)
  • I have added proper labels to this PR
  • I have installed and executed pre-commit (no code changes; markdown only)

…tions

Follow-up to #13360 and tracked in #13359. This change implements the
remaining audit findings for the entire v3.x changelog (3.0.0 through
3.16.0): backfill missing patch sections, expand or rewrite entries to
reflect real user impact, mark breaking changes with `:warning:`, and
add user-visible PRs that were previously omitted.

Highlights:

- Backfill 3.2.2 / 3.4.1 / 3.8.1 / 3.9.1 sections that existed on the
  `release/3.x` branches but were never cherry-picked back to master.
  Each backfilled section carries the original release-branch text;
  jwt-auth bypass (#9837) and forward-auth POST header leak (#11184)
  are now labelled `:warning:` under a `### Security` subsection where
  applicable.
- Replace the 3.2.1 placeholder paragraph with the 5-6 real bugfixes
  from `release/3.2` (incl. the missing #9309 proxy-rewrite fix).
- 3.16.0: add #12961 ai-proxy header forwarding fix; mark #13046 and
  #13057 `:warning:` and rewrite #13006 / #13066 / #13030 for users.
- 3.15.0: mark #12862 (lua-resty-session 4.x AES-256-GCM default forces
  OIDC re-auth) and #12714 / #12678 `:warning:`; aggregate dep bumps.
- 3.14.0: move #12551 X-Forwarded-* trusted-source change from Bugfixes
  to Change with `:warning:` and the `trusted_addresses` upgrade hint.
- 3.13.0 / 3.12.0 / 3.11.0 / 3.10.0 / 3.9.0 / 3.8.0 / 3.7.0 / 3.6.0 /
  3.5.0 / 3.4.0 / 3.3.0 / 3.2.0 / 3.1.0 / 3.0.0: add missing user-facing
  PRs, expand implementation-side wording to user-side, fix dropped
  rockspec dep bumps, deduplicate entries listed in two subsections,
  and add `:warning:` flags where the schema/default-value scan flagged
  silent breaking changes (incl. #11993 ssl_trusted_certificate, #11601
  credential resource, #11581 hmac-auth field rename, #10393 OTel span
  name, #10233 strict schema scope, #11343 config-default.yaml removal,
  #11312 lyaml stricter parsing, #10469 kafka-logger required_acks=0,
  #9622 google-cloud-logging client_email, #8660 jwt-auth Vault removed,
  #8180 upstream type optional).

Diff: +240 / -77 lines.

Refs #13359.
@membphis membphis added the doc Documentation things label May 12, 2026
@dosubot dosubot Bot added the size:L This PR changes 100-499 lines, ignoring generated files. label May 12, 2026
The `ci/check_changelog_prs.ts` script captures only the first `#NNNN`
match per line. Four entries from the previous commit listed a related
PR (or an external-repo reference like `api7/apisix-nginx-module#108`)
before the entry's own PR number, so the check reported the entries'
own PRs as missing from CHANGELOG.md. Reorder so that the entry's
canonical PR appears first on the line:

- 3.15.0 #12678 (apisix-runtime init_worker)
- 3.13.0 #12244 (server-info deprecation)
- 3.10.0 #11095 (encrypted plugin fields expansion)
- 3.8.1  #11174 (forward-auth POST headers)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Documentation things size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants