[
https://issues.apache.org/jira/browse/KAFKA-21328?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
PoAn Yang reassigned KAFKA-21328:
---------------------------------
Assignee: PoAn Yang
> 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
> Assignee: PoAn Yang
> Priority: Minor
>
> 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
(v10.3.26#10030026)
