Versions Compared

Old Version 3

changes.mady.by.user Manikumar Reddy O.

Saved on

compared with

New Version Current

changes.mady.by.user Tom Bentley

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Update for start-preview.sh

The website documentation of Kafka resides in a few different places. 

Kafka Code Repository

  •  Kafka code repo has a /docs directory with the latest revision of the docs (not multiple versions, just one that matches the latest state of code).

  • When you submit a code patch that requires doc modification, you modify all relevant files in same patch and they get reviewed and committed together (ideally). 

  • When you submit a doc patch alone, you modify all relevant files in docs/ directory and submit a patch.

  • Broker/producer/consumer configuration docs are auto-generated from code. So for any changes, you need to modify the relevant java files (KafkaConfig.java, ProducerConfig.java, ConsumerConfig.java etc).

  • Follow Contributing Code Changes for submitting above doc changes using  Github Github pull requests.

  • When we release, we copy the docs matching the release and commit to to the website git repo. We also do this occasionally to fix bugs in earlier docs.

  • For older releases, contribute changes to the relevant branch of the release code repository and this will be pushed to the website git repo as needed.

Kafka Website Repository

  • The website git repo hosts some of the Kafka website pages that are not included in the Kafka code repository.

  • In some cases, like hot fixes, non-technical web page changes, we accept Github pull requests against website git repo. However the Kafka code repo is the "source of truth" for any and all documentation, except for what is only included in the website git repo. You should always check the docs in the Kafka code repo and make any necessary changes or fixes there before you open a pull request against the website git repo.
     

  • There are a number of ways to preview edits on the web docs

    • Recommended: Use the start-preview.sh script in the website repo. This requires you have Docker or Podman installed. Running the script will create a container image containing httpd and the necessary server config. You then just need to point your browser at localhost:8080.

    • Alternatively, setup your local web server to point to your kafka-site repo (it is a one time thing and will save you lots of time moving forward if you are going to continuously contributing to web doc changes),

    • You can also extract the content inside the

      Code Block
      <script id="api-template" type="text/x-handlebars-template">

...

</script>



<div class="p-api"></div> 


      JavaScript wrapper in order to display it with a browser (it will lose the formatting decorations though).

Wiki Pages

  • Some documentation are simply wiki pages. In that case, we simply modify the wiki pages. (You may need permission to modify the wiki pages. Please send email to dev@kafka.apache.org or users@kafka.apache.org asking for the permission.)