Omnia Ibrahim created KAFKA-21328:
-------------------------------------
Summary: Add CI check for stale version references in docs/
Key: KAFKA-21328
URL: https://issues.apache.org/jira/browse/KAFKA-21328
Project: Kafka
Issue Type: Improvement
Reporter: Omnia Ibrahim
Kafka's documentation under \{{docs/}} (Hugo source for kafka-site) contains
hardcoded version references in structured contexts:
* Maven \{{<version>}} coordinates,
* Docker image tags (\{{apache/kafka:X.Y.Z}}),
* tarball/jar names (\{{kafka_2.13-X.Y.Z.tgz}}, {\{connect-file-X.Y.Z.jar}}),
* GitHub source links (\{{blob/X.Y/...}}),
* archetype versions (\{{-DarchetypeVersion=X.Y.Z}}),
* andjavadoc link titles ("Kafka X.Y Javadoc").
When a doc page is created by copy-pasting from an existing page (very common),
these version strings are frequently carried over unchanged and never updated.
They then silently go stale until someone notices during a release — e.g. the
4.4 docs still referenced 4.3 in numerous places, caught only by manual review
during release staging.
I would like to propose an automated guard against this to prevent stale
references accumulate across a release cycle and land on the release manager at
staging time — the worst place to triage them, since the RM lacks the context
for every line written months earlier by other contributors.
*Proposal:*
Add a CI check (new workflow + script under \{{.github/scripts/}}) that runs on
any PR touching \{{docs/**}}, including on trunk (trunk is where most stale
references are first introduced).
The check asserts that a small set of *high-signal, structured* version
patterns resolve to the current version (derived from \{{gradle.properties}}),
and flags any that point at a different, non-\{{trunk}} version:
* \{{<version>X.Y.Z</version>}} and the sbt \{{% "X.Y.Z"}} form
* {\{apache/kafka:X.Y.Z}}, \{{apache/kafka-native:X.Y.Z}}
* {\{kafka_2.13-X.Y.Z.tgz}} / \{{kafka_2.13-X.Y.Z}}
* {\{connect-file-X.Y.Z.jar}}, \{{kafka-storage-X.Y.Z-test.jar}}
* {\{-DarchetypeVersion=X.Y.Z}}
* {\{blob/X.Y/}} (allowing \{{blob/trunk/}})
* "Kafka X.Y Javadoc"
* {\{git checkout X.Y.Z}}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
