[
https://issues.apache.org/jira/browse/KAFKA-21328?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Omnia Ibrahim updated KAFKA-21328:
----------------------------------
Description:
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{}}}, {Unknown macro: \{apache/kafka-native}}
* {{kafka_2.13-X.Y.Z.tgz}} / {Unknown macro: \{kafka_2.13-X.Y.Z}}
* {{{}connect-file-X.Y.Z.jar{}}}, {Unknown macro:
\{kafka-storage-X.Y.Z-test.jar}}
*
Unknown macro: \{{-DarchetypeVersion=X.Y.Z}}
* {{blob/X.Y/}} (allowing {{{}blob/trunk/{}}})
* "Kafka X.Y Javadoc"
* {\\{git checkout X.Y.Z}}
was:
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}}
> 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{}}}, {Unknown macro: \{apache/kafka-native}}
> * {{kafka_2.13-X.Y.Z.tgz}} / {Unknown macro: \{kafka_2.13-X.Y.Z}}
> * {{{}connect-file-X.Y.Z.jar{}}}, {Unknown macro:
> \{kafka-storage-X.Y.Z-test.jar}}
> *
> Unknown macro: \{{-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)
