Metastarx opened a new pull request, #11197: URL: https://github.com/apache/rocketmq/pull/11197
### Which Issue(s) This PR Fixes https://github.com/apache/rocketmq/issues/11159 - Fixes #11159 ### Brief Description ### Search before creation - [x] I had searched in the [issues](https://github.com/apache/rocketmq/issues) and found no similar issues. ### Documentation Related The quick-start docs give the Gradle dependency as: ``` compile 'org.apache.rocketmq:rocketmq-client:5.5.0' ``` Gradle removed the `compile` configuration in 7.0, so this no longer works. Reproduced on Gradle 9.7.1 with an otherwise empty `java` project: ``` * What went wrong: A problem occurred evaluating root project '...'. > Could not find method compile() for arguments [org.apache.rocketmq:rocketmq-client:5.5.0] on object of type org.gradle.api.internal.artifacts.dsl.dependencies.DefaultDependencyHandler. ``` The error doesn't hint at the cause. Gradle's own suggestions are just `--stacktrace` / `--info` / `--scan`, and it fails while evaluating the project, so it reads like a method-name typo rather than a removed configuration. Swapping in `implementation` builds fine and resolves `rocketmq-client:5.5.0` along with its transitive dependencies from Maven Central, so the coordinates and the version in the docs are correct and only the configuration name is stale. Affected files: - `docs/en/Example_Simple.md` - `docs/cn/Example_Simple_cn.md` - `docs/cn/RocketMQ_Example.md` The Maven blocks right above them are fine. Since the repo builds with Maven and Bazel only, no CI job ever looks at these snippets, which is probably how it drifted. I checked the in-flight docs PRs first. #10436 and #10409 both touch these same lines, but they only bump the version number inside the snippet and keep `compile`, so this doesn't overlap with them. ### Are you willing to submit PR? - [x] Yes I am willing to submit a PR! ### How Did You Test This Change? PASSED: wsl -e bash scripts/gate-rocketmq.sh <details><summary>补充说明</summary> ## 背景 ### Search before creation - [x] I had searched in the [issues](https://github.com/apache/rocketmq/issues) and found no similar issues. ### Documentation Related The quick-start docs give the Gradle dependency as: ``` compile 'org.apache.rocketmq:rocketmq-client:5.5.0' ``` Gradle removed the `compile` configuration in 7.0, so this no longer works. Reproduced on Gradle 9.7.1 with an otherwise empty `java` project: ``` * What went wrong: A problem occurred evaluating root project '...'. > Could not find method compile() for arguments [org.apache.rocketmq:rocketmq-client:5.5.0] on object of type org.gradle.api.internal.artifacts.dsl.dependencies.DefaultDependencyHandler. ``` The error doesn't hint at the cause. Gradle's own suggestions are just `--stacktrace` / `--info` / `--scan`, and it fails while evaluating the project, so it reads like a method-name typo rather than a removed configuration. Swapping in `implementation` builds fine and resolves `rocketmq-client:5.5.0` along with its transitive dependencies from Maven Central, so the coordinates and the version in the docs are correct and only the configuration name is stale. Affected files: - `docs/en/Example_Simple.md` - `docs/cn/Example_Simple_cn.md` - `docs/cn/RocketMQ_Example.md` The Maven blocks right above them are fine. Since the repo builds with Maven and Bazel only, no CI job ever looks at these snippets, which is probably how it drifted. I checked the in-flight docs PRs first. #10436 and #10409 both touch these same lines, but they only bump the version number inside the snippet and keep `compile`, so this doesn't overlap with them. ### Are you willing to submit PR? - [x] Yes I am willing to submit a PR! 相关 Issue：https://github.com/apache/rocketmq/issues/11159 ## 变更内容 ```diff diff --git a/docs/cn/Example_Simple_cn.md b/docs/cn/Example_Simple_cn.md --- a/docs/cn/Example_Simple_cn.md +++ b/docs/cn/Example_Simple_cn.md @@ -13,7 +13,13 @@ </dependency> ``` gradle: -``` java -compile 'org.apache.rocketmq:rocketmq-client:5.5.0' +``` groovy +repositories { + mavenCentral() +} +dependencies { + implementation 'org.apache.rocketmq:rocketmq-client:5.5.0' +} ``` +Gradle 7.0 已移除 `compile` 配置，请改用 `implementation`；如果 RocketMQ 类型出现在你自己的公共 API 中，则应使用 `api`。 ### 2 发送消息 diff --git a/docs/cn/RocketMQ_Example.md b/docs/cn/RocketMQ_Example.md --- a/docs/cn/RocketMQ_Example.md +++ b/docs/cn/RocketMQ_Example.md @@ -59,6 +59,12 @@ ``` `gradle` ``` -compile 'org.apache.rocketmq:rocketmq-client:5.5.0' +repositories { + mavenCentral() +} +dependencies { + implementation 'org.apache.rocketmq:rocketmq-client:5.5.0' +} ``` +Gradle 7.0 已移除 `compile` 配置，请改用 `implementation`；如果 RocketMQ 类型出现在你自己的公共 API 中，则应使用 `api`。 ### 1.2 消息发送 diff --git a/docs/en/Example_Simple.md b/docs/en/Example_Simple.md --- a/docs/en/Example_Simple.md +++ b/docs/en/Example_Simple.md @@ -13,7 +13,13 @@ </dependency> ``` gradle: -``` java -compile 'org.apache.rocketmq:rocketmq-client:5.5.0' +``` groovy +repositories { + mavenCentral() +} +dependencies { + implementation 'org.apache.rocketmq:rocketmq-client:5.5.0' +} ``` +Gradle 7.0 removed the `compile` configuration, so declare the dependency with `implementation` (use `api` instead when RocketMQ types are exposed in your own public API). ### 2 Send Messages diff --git a/test/src/main/java/org/apache/rocketmq/test/docs/DependencyDeclaration.java b/test/src/main/java/org/apache/rocketmq/test/docs/DependencyDeclaration.java new file mode 100644 --- /dev/null +++ b/test/src/main/java/org/apache/rocketmq/test/docs/DependencyDeclaration.java @@ -0,0 +1,96 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.rocketmq.test.docs; + +/** + * A single build dependency declaration parsed from a fenced code block of a Markdown document. + * + * <p>The quick-start pages are meant to be copy-and-paste ready, so a stale entry is not a cosmetic + * problem: the reader pastes it into an empty project and the build fails before the first RocketMQ + * class is loaded. Keeping the parsed line as a small value object lets {@link DocsDependencyChecker} + * report the exact document, line and configuration that need to be corrected. + */ +public class DependencyDeclaration { + private final String sourceFile; + private final int lineNumber; + private final String configuration; + private final String coordinate; + private final String groupId; + private final String artifactId; + private final String version; + + public DependencyDeclaration(String sourceFile, int lineNumber, String configuration, String coordinate) { + this.sourceFile = sourceFile; + this.lineNumber = lineNumber; + this.configuration = configuration; + this.coordinate = coordinate; + String[] parts = coordinate.split(":"); + this.groupId = parts[0].trim(); + this.artifactId = parts.length > 1 ? parts[1].trim() : ""; + this.version = parts.length > 2 ? parts[2].trim() : ""; + } + + public String getSourceFile() { + return sourceFile; + } + + public int getLineNumber() { + return lineNumber; + } + + public String getConfiguration() { + return configuration; + } + + public String getCoordinate() { + return coordinate; + } + + public String getGroupId() { + return groupId; + } + + public String getArtifactId() { + return artifactId; + } + + public String getVersion() { + return version; + } + + /** + * Returns the {@code group:artifact} key used to compare the versions of one dependency across + * documents, for example {@code org.apache.rocketmq:rocketmq-client}. + */ + public String getGroupArtifact() { + return groupId + ":" + artifactId; + } + + /** + * Returns {@code true} when the coordinate pins a version. Coordinates without a version cannot + * be compared with each other, so they are ignored by the version consistency rule. + */ + public boolean hasVersion() { + return !version.isEmpty(); + } + + @Override + public String toString() { + return sourceFile + ":" + lineNumber + " " + configuration + " '" + coordinate + "'"; + } +} diff --git a/test/src/main/java/org/apache/rocketmq/test/docs/DocsDependencyChecker.java b/test/src/main/java/org/apache/rocketmq/test/docs/DocsDependencyChecker.java new file mode 100644 --- /dev/null +++ b/test/src/main/java/org/apache/rocketmq/test/docs/DocsDependencyChecker.java @@ -0,0 +1,232 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.rocketmq.test.docs; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.stream.Collectors; +import java.util.stream.Stream; + +/** + * Validates the build snippets that the documentation asks readers to copy. + * ``` ## 验证 PASSED: wsl -e bash scripts/gate-rocketmq.sh ## 检查清单 - [x] 已通过本地测试 - [x] 变更最小且不包含无关文件 - [x] 已遵守仓库贡献规范 </details> -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
