mimaison commented on code in PR #18027: URL: https://github.com/apache/kafka/pull/18027#discussion_r1869276639
########## README.md: ########## @@ -1,55 +1,105 @@ -Apache Kafka -================= -See our [web site](https://kafka.apache.org) for details on the project. - -You need to have [Java](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed. - -We build and test Apache Kafka with 17 and 23. The `release` parameter in javac and scalac is set to `11` for the clients -and streams modules, and `17` for the broker and tools, ensuring compatibility with their respective minimum Java versions. - -Scala 2.13 is the only supported version in Apache Kafka. - -### Build a jar and run it ### +# Apache Kafka + +<a href="https://kafka.apache.org/";> +<picture> + <source media="(prefers-color-scheme: dark)" srcset="docs/images/kafka-logo-readme-dark.svg"> + <source media="(prefers-color-scheme: light)" srcset="docs/images/kafka-logo-readme-light.svg"> + <img alt="Kafka Logo" src="docs/images/kafka-logo-readme-light.svg" width="80"> +</picture> +</a> +<br><br> + +* [Building Kafka](#building-kafka) + * [Prerequisites](#prerequisites) + * [Build steps](#build-steps) + * [Build a jar and run it](#build-a-jar-and-run-it) + * [Build source jar](#build-source-jar) + * [Build aggregated javadoc](#build-aggregated-javadoc) + * [Build javadoc and scaladoc](#build-javadoc-and-scaladoc) +* [Testing Kafka](#testing-kafka) + * [Run unit/integration tests](#run-unitintegration-tests) + * [Force re-running tests without code change](#force-re-running-tests-without-code-change) + * [Running a particular unit/integration test](#running-a-particular-unitintegration-test) + * [Repeatedly running a particular unit/integration test with specific times by setting N](#repeatedly-running-a-particular-unitintegration-test-with-specific-times-by-setting-n) + * [Running a particular test method within a unit/integration test](#running-a-particular-test-method-within-a-unitintegration-test) + * [Running a particular unit/integration test with log4j output](#running-a-particular-unitintegration-test-with-log4j-output) + * [Specifying test retries](#specifying-test-retries) +* [Running a Kafka broker in KRaft mode](#running-a-kafka-broker-in-kraft-mode) + * [Using compiled files](#using-compiled-files) + * [Using docker image](#using-docker-image) +* [Test Coverage](#test-coverage) + * [Generating test coverage reports](#generating-test-coverage-reports) +* [Other Actions](#other-actions) + * [Building a binary release gzipped tarball](#building-a-binary-release-gzipped-tar-ball) + * [Building auto generated messages](#building-auto-generated-messages) + * [Cleaning the build](#cleaning-the-build) + * [Running a task for a specific project](#running-a-task-for-a-specific-project) + * [Listing all gradle tasks](#listing-all-gradle-tasks) + * [Building IDE project](#building-ide-project) + * [Publishing the streams quickstart archetype artifact to maven](#publishing-the-streams-quickstart-archetype-artifact-to-maven) + * [Installing specific projects to the local Maven repository](#installing-specific-projects-to-the-local-maven-repository) + * [Building the test jar](#building-the-test-jar) +* [Running code quality checks](#running-code-quality-checks) + * [Checkstyle](#checkstyle) + * [Spotless](#spotless) + * [Spotbugs](#spotbugs) +* [JMH microbenchmarks](#jmh-microbenchmarks) +* [Dependency Analysis](#dependency-analysis) + * [Determining if any dependencies could be updated](#determining-if-any-dependencies-could-be-updated) +* [Common build options](#common-build-options) +* [Running system tests](#running-system-tests) +* [Running in Vagrant](#running-in-vagrant) +* [Contributing Kafka](#contributing-kafka) + +# Building Kafka <a name="building-kafka"></a> Review Comment: Do we really need these `<a>` tags? Markdown automatically create links for all sections. You can already use URL fragments to point to specific sections, for example https://github.com/apache/kafka#build-a-jar-and-run-it ########## README.md: ########## @@ -1,55 +1,105 @@ -Apache Kafka -================= -See our [web site](https://kafka.apache.org) for details on the project. - -You need to have [Java](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed. - -We build and test Apache Kafka with 17 and 23. The `release` parameter in javac and scalac is set to `11` for the clients -and streams modules, and `17` for the broker and tools, ensuring compatibility with their respective minimum Java versions. - -Scala 2.13 is the only supported version in Apache Kafka. - -### Build a jar and run it ### +# Apache Kafka + +<a href="https://kafka.apache.org/";> +<picture> + <source media="(prefers-color-scheme: dark)" srcset="docs/images/kafka-logo-readme-dark.svg"> + <source media="(prefers-color-scheme: light)" srcset="docs/images/kafka-logo-readme-light.svg"> + <img alt="Kafka Logo" src="docs/images/kafka-logo-readme-light.svg" width="80"> +</picture> +</a> +<br><br> + +* [Building Kafka](#building-kafka) + * [Prerequisites](#prerequisites) + * [Build steps](#build-steps) + * [Build a jar and run it](#build-a-jar-and-run-it) + * [Build source jar](#build-source-jar) + * [Build aggregated javadoc](#build-aggregated-javadoc) + * [Build javadoc and scaladoc](#build-javadoc-and-scaladoc) +* [Testing Kafka](#testing-kafka) + * [Run unit/integration tests](#run-unitintegration-tests) + * [Force re-running tests without code change](#force-re-running-tests-without-code-change) + * [Running a particular unit/integration test](#running-a-particular-unitintegration-test) + * [Repeatedly running a particular unit/integration test with specific times by setting N](#repeatedly-running-a-particular-unitintegration-test-with-specific-times-by-setting-n) + * [Running a particular test method within a unit/integration test](#running-a-particular-test-method-within-a-unitintegration-test) + * [Running a particular unit/integration test with log4j output](#running-a-particular-unitintegration-test-with-log4j-output) + * [Specifying test retries](#specifying-test-retries) +* [Running a Kafka broker in KRaft mode](#running-a-kafka-broker-in-kraft-mode) + * [Using compiled files](#using-compiled-files) + * [Using docker image](#using-docker-image) +* [Test Coverage](#test-coverage) + * [Generating test coverage reports](#generating-test-coverage-reports) +* [Other Actions](#other-actions) + * [Building a binary release gzipped tarball](#building-a-binary-release-gzipped-tar-ball) + * [Building auto generated messages](#building-auto-generated-messages) + * [Cleaning the build](#cleaning-the-build) + * [Running a task for a specific project](#running-a-task-for-a-specific-project) + * [Listing all gradle tasks](#listing-all-gradle-tasks) + * [Building IDE project](#building-ide-project) + * [Publishing the streams quickstart archetype artifact to maven](#publishing-the-streams-quickstart-archetype-artifact-to-maven) + * [Installing specific projects to the local Maven repository](#installing-specific-projects-to-the-local-maven-repository) + * [Building the test jar](#building-the-test-jar) +* [Running code quality checks](#running-code-quality-checks) + * [Checkstyle](#checkstyle) + * [Spotless](#spotless) + * [Spotbugs](#spotbugs) +* [JMH microbenchmarks](#jmh-microbenchmarks) +* [Dependency Analysis](#dependency-analysis) + * [Determining if any dependencies could be updated](#determining-if-any-dependencies-could-be-updated) +* [Common build options](#common-build-options) +* [Running system tests](#running-system-tests) +* [Running in Vagrant](#running-in-vagrant) +* [Contributing Kafka](#contributing-kafka) + +# Building Kafka <a name="building-kafka"></a> + +[**Apache Kafka**](https://kafka.apache.org) is an open-source distributed event streaming platform used by thousands of companies for high-performance data pipelines, streaming analytics, data integration, and mission-critical applications. Review Comment: No sure this fits under `Building Kafka`. It seems more like an introduction, so I think it should be above (maybe even above the ToC) ########## README.md: ########## @@ -1,55 +1,105 @@ -Apache Kafka -================= -See our [web site](https://kafka.apache.org) for details on the project. - -You need to have [Java](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed. - -We build and test Apache Kafka with 17 and 23. The `release` parameter in javac and scalac is set to `11` for the clients -and streams modules, and `17` for the broker and tools, ensuring compatibility with their respective minimum Java versions. - -Scala 2.13 is the only supported version in Apache Kafka. - -### Build a jar and run it ### +# Apache Kafka + +<a href="https://kafka.apache.org/";> +<picture> + <source media="(prefers-color-scheme: dark)" srcset="docs/images/kafka-logo-readme-dark.svg"> + <source media="(prefers-color-scheme: light)" srcset="docs/images/kafka-logo-readme-light.svg"> + <img alt="Kafka Logo" src="docs/images/kafka-logo-readme-light.svg" width="80"> +</picture> +</a> +<br><br> + +* [Building Kafka](#building-kafka) + * [Prerequisites](#prerequisites) + * [Build steps](#build-steps) + * [Build a jar and run it](#build-a-jar-and-run-it) + * [Build source jar](#build-source-jar) + * [Build aggregated javadoc](#build-aggregated-javadoc) + * [Build javadoc and scaladoc](#build-javadoc-and-scaladoc) +* [Testing Kafka](#testing-kafka) + * [Run unit/integration tests](#run-unitintegration-tests) + * [Force re-running tests without code change](#force-re-running-tests-without-code-change) + * [Running a particular unit/integration test](#running-a-particular-unitintegration-test) + * [Repeatedly running a particular unit/integration test with specific times by setting N](#repeatedly-running-a-particular-unitintegration-test-with-specific-times-by-setting-n) + * [Running a particular test method within a unit/integration test](#running-a-particular-test-method-within-a-unitintegration-test) + * [Running a particular unit/integration test with log4j output](#running-a-particular-unitintegration-test-with-log4j-output) + * [Specifying test retries](#specifying-test-retries) +* [Running a Kafka broker in KRaft mode](#running-a-kafka-broker-in-kraft-mode) + * [Using compiled files](#using-compiled-files) + * [Using docker image](#using-docker-image) +* [Test Coverage](#test-coverage) + * [Generating test coverage reports](#generating-test-coverage-reports) +* [Other Actions](#other-actions) + * [Building a binary release gzipped tarball](#building-a-binary-release-gzipped-tar-ball) + * [Building auto generated messages](#building-auto-generated-messages) + * [Cleaning the build](#cleaning-the-build) + * [Running a task for a specific project](#running-a-task-for-a-specific-project) + * [Listing all gradle tasks](#listing-all-gradle-tasks) + * [Building IDE project](#building-ide-project) + * [Publishing the streams quickstart archetype artifact to maven](#publishing-the-streams-quickstart-archetype-artifact-to-maven) + * [Installing specific projects to the local Maven repository](#installing-specific-projects-to-the-local-maven-repository) + * [Building the test jar](#building-the-test-jar) +* [Running code quality checks](#running-code-quality-checks) + * [Checkstyle](#checkstyle) + * [Spotless](#spotless) + * [Spotbugs](#spotbugs) +* [JMH microbenchmarks](#jmh-microbenchmarks) +* [Dependency Analysis](#dependency-analysis) + * [Determining if any dependencies could be updated](#determining-if-any-dependencies-could-be-updated) +* [Common build options](#common-build-options) +* [Running system tests](#running-system-tests) +* [Running in Vagrant](#running-in-vagrant) +* [Contributing Kafka](#contributing-kafka) + +# Building Kafka <a name="building-kafka"></a> + +[**Apache Kafka**](https://kafka.apache.org) is an open-source distributed event streaming platform used by thousands of companies for high-performance data pipelines, streaming analytics, data integration, and mission-critical applications. + +## Prerequisites <a name="prerequisites"></a> +* You need to have [Java 8+](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed. +* KRaft or ZooKeeper +* Apache Kafka is built and tested using Java versions 17 and 23. However, to ensure maximum compatibility, the Kafka client and streams modules are compiled to work with Java 11 and later, while the broker and tools require Java 17 or later. Review Comment: `client` -> `clients` ########## README.md: ########## @@ -1,55 +1,105 @@ -Apache Kafka -================= -See our [web site](https://kafka.apache.org) for details on the project. - -You need to have [Java](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed. - -We build and test Apache Kafka with 17 and 23. The `release` parameter in javac and scalac is set to `11` for the clients -and streams modules, and `17` for the broker and tools, ensuring compatibility with their respective minimum Java versions. - -Scala 2.13 is the only supported version in Apache Kafka. - -### Build a jar and run it ### +# Apache Kafka + +<a href="https://kafka.apache.org/";> +<picture> + <source media="(prefers-color-scheme: dark)" srcset="docs/images/kafka-logo-readme-dark.svg"> + <source media="(prefers-color-scheme: light)" srcset="docs/images/kafka-logo-readme-light.svg"> + <img alt="Kafka Logo" src="docs/images/kafka-logo-readme-light.svg" width="80"> +</picture> +</a> +<br><br> + +* [Building Kafka](#building-kafka) + * [Prerequisites](#prerequisites) + * [Build steps](#build-steps) + * [Build a jar and run it](#build-a-jar-and-run-it) + * [Build source jar](#build-source-jar) + * [Build aggregated javadoc](#build-aggregated-javadoc) + * [Build javadoc and scaladoc](#build-javadoc-and-scaladoc) +* [Testing Kafka](#testing-kafka) + * [Run unit/integration tests](#run-unitintegration-tests) + * [Force re-running tests without code change](#force-re-running-tests-without-code-change) + * [Running a particular unit/integration test](#running-a-particular-unitintegration-test) + * [Repeatedly running a particular unit/integration test with specific times by setting N](#repeatedly-running-a-particular-unitintegration-test-with-specific-times-by-setting-n) + * [Running a particular test method within a unit/integration test](#running-a-particular-test-method-within-a-unitintegration-test) + * [Running a particular unit/integration test with log4j output](#running-a-particular-unitintegration-test-with-log4j-output) + * [Specifying test retries](#specifying-test-retries) +* [Running a Kafka broker in KRaft mode](#running-a-kafka-broker-in-kraft-mode) + * [Using compiled files](#using-compiled-files) + * [Using docker image](#using-docker-image) +* [Test Coverage](#test-coverage) + * [Generating test coverage reports](#generating-test-coverage-reports) +* [Other Actions](#other-actions) + * [Building a binary release gzipped tarball](#building-a-binary-release-gzipped-tar-ball) + * [Building auto generated messages](#building-auto-generated-messages) + * [Cleaning the build](#cleaning-the-build) + * [Running a task for a specific project](#running-a-task-for-a-specific-project) + * [Listing all gradle tasks](#listing-all-gradle-tasks) + * [Building IDE project](#building-ide-project) + * [Publishing the streams quickstart archetype artifact to maven](#publishing-the-streams-quickstart-archetype-artifact-to-maven) + * [Installing specific projects to the local Maven repository](#installing-specific-projects-to-the-local-maven-repository) + * [Building the test jar](#building-the-test-jar) +* [Running code quality checks](#running-code-quality-checks) + * [Checkstyle](#checkstyle) + * [Spotless](#spotless) + * [Spotbugs](#spotbugs) +* [JMH microbenchmarks](#jmh-microbenchmarks) +* [Dependency Analysis](#dependency-analysis) + * [Determining if any dependencies could be updated](#determining-if-any-dependencies-could-be-updated) +* [Common build options](#common-build-options) +* [Running system tests](#running-system-tests) +* [Running in Vagrant](#running-in-vagrant) +* [Contributing Kafka](#contributing-kafka) + +# Building Kafka <a name="building-kafka"></a> + +[**Apache Kafka**](https://kafka.apache.org) is an open-source distributed event streaming platform used by thousands of companies for high-performance data pipelines, streaming analytics, data integration, and mission-critical applications. + +## Prerequisites <a name="prerequisites"></a> +* You need to have [Java 8+](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed. +* KRaft or ZooKeeper Review Comment: I'm not sure I consider KRaft a prerequisite since it's part of Kafka. ########## docs/images/kafka-logo-readme-dark.svg: ########## Review Comment: The logo is a registered trademark and I'm not sure we can just swap its colors. ########## README.md: ########## @@ -1,55 +1,105 @@ -Apache Kafka -================= -See our [web site](https://kafka.apache.org) for details on the project. - -You need to have [Java](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed. - -We build and test Apache Kafka with 17 and 23. The `release` parameter in javac and scalac is set to `11` for the clients -and streams modules, and `17` for the broker and tools, ensuring compatibility with their respective minimum Java versions. - -Scala 2.13 is the only supported version in Apache Kafka. - -### Build a jar and run it ### +# Apache Kafka + +<a href="https://kafka.apache.org/";> +<picture> + <source media="(prefers-color-scheme: dark)" srcset="docs/images/kafka-logo-readme-dark.svg"> + <source media="(prefers-color-scheme: light)" srcset="docs/images/kafka-logo-readme-light.svg"> + <img alt="Kafka Logo" src="docs/images/kafka-logo-readme-light.svg" width="80"> +</picture> +</a> +<br><br> + +* [Building Kafka](#building-kafka) + * [Prerequisites](#prerequisites) + * [Build steps](#build-steps) + * [Build a jar and run it](#build-a-jar-and-run-it) + * [Build source jar](#build-source-jar) + * [Build aggregated javadoc](#build-aggregated-javadoc) + * [Build javadoc and scaladoc](#build-javadoc-and-scaladoc) +* [Testing Kafka](#testing-kafka) + * [Run unit/integration tests](#run-unitintegration-tests) + * [Force re-running tests without code change](#force-re-running-tests-without-code-change) + * [Running a particular unit/integration test](#running-a-particular-unitintegration-test) + * [Repeatedly running a particular unit/integration test with specific times by setting N](#repeatedly-running-a-particular-unitintegration-test-with-specific-times-by-setting-n) + * [Running a particular test method within a unit/integration test](#running-a-particular-test-method-within-a-unitintegration-test) + * [Running a particular unit/integration test with log4j output](#running-a-particular-unitintegration-test-with-log4j-output) + * [Specifying test retries](#specifying-test-retries) +* [Running a Kafka broker in KRaft mode](#running-a-kafka-broker-in-kraft-mode) + * [Using compiled files](#using-compiled-files) + * [Using docker image](#using-docker-image) +* [Test Coverage](#test-coverage) + * [Generating test coverage reports](#generating-test-coverage-reports) +* [Other Actions](#other-actions) + * [Building a binary release gzipped tarball](#building-a-binary-release-gzipped-tar-ball) + * [Building auto generated messages](#building-auto-generated-messages) + * [Cleaning the build](#cleaning-the-build) + * [Running a task for a specific project](#running-a-task-for-a-specific-project) + * [Listing all gradle tasks](#listing-all-gradle-tasks) + * [Building IDE project](#building-ide-project) + * [Publishing the streams quickstart archetype artifact to maven](#publishing-the-streams-quickstart-archetype-artifact-to-maven) + * [Installing specific projects to the local Maven repository](#installing-specific-projects-to-the-local-maven-repository) + * [Building the test jar](#building-the-test-jar) +* [Running code quality checks](#running-code-quality-checks) + * [Checkstyle](#checkstyle) + * [Spotless](#spotless) + * [Spotbugs](#spotbugs) +* [JMH microbenchmarks](#jmh-microbenchmarks) +* [Dependency Analysis](#dependency-analysis) + * [Determining if any dependencies could be updated](#determining-if-any-dependencies-could-be-updated) +* [Common build options](#common-build-options) +* [Running system tests](#running-system-tests) +* [Running in Vagrant](#running-in-vagrant) +* [Contributing Kafka](#contributing-kafka) + +# Building Kafka <a name="building-kafka"></a> + +[**Apache Kafka**](https://kafka.apache.org) is an open-source distributed event streaming platform used by thousands of companies for high-performance data pipelines, streaming analytics, data integration, and mission-critical applications. + +## Prerequisites <a name="prerequisites"></a> +* You need to have [Java 8+](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed. Review Comment: Trunk now requires Java 11+. The latest release, 3.9.0, still support Java 8 but since you pointed below that we target 11, let's be consistent. Also I'm not sure we want to point to Oracle for getting a JVM. ########## docs/images/kafka-logo-readme-light.svg: ########## Review Comment: Why can't we use the existing logo? ########## README.md: ########## @@ -72,42 +122,41 @@ The quarantinedTest task also has no retries by default, but you can set maxQuar See [Test Retry Gradle Plugin](https://github.com/gradle/test-retry-gradle-plugin) for and [build.yml](.github/workflows/build.yml) more details. -### Generating test coverage reports ### -Generate coverage reports for the whole project: +# Running a Kafka broker in KRaft mode <a name="running-a-kafka-broker-in-kraft-mode"></a> Review Comment: I actually wonder if we should remove this copy of the quickstart and only have it on the website. The fact that it's out of date, still pointing to the `apache/kafka:3.7.0` docker image, makes me think we should have a single copy. -- 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: jira-unsubscr...@kafka.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
