Skip to main content

Updating document

This guide explains the organization of Pulsar documentation and website repos and the workflow of updating various Pulsar documents.

Source repositories​

Currently, the source of documents and website (where the docs are finally published) are located at the apache/pulsar-site repo.

Update versioned docs​

Documentation should be up to date for all actively supported versions.

No need to update documentation for versions that are not actively maintained unless the documentation is incorrect.

To update versioned docs, go to versioned_docs folder.

For versions prior to 2.8, Pulsar releases versioned docs for each patch release. You can update the exact versioned doc.

For versions start from 2.8, Pulsar release versioned docs for each minor release. Apart from updating the content, you should take care of adding specific instructions.

For example, if you want to add docs for an improvement introduced in 2.8.2, you can add the following instructions:

:::note

This <fix / improvment> is available for 2.8.2 and later versions.

:::

Update reference docs​

If you want to update Pulsar reference docs, you should update the corresponding source files.

  • Some reference docs are generated from code automatically. If you want to update the docs, you need to update the source code files.
  • Some configuration docs are updated manually using markdown files.

Update configuration docs​

Docs for configs of bundled components are generated from command-line tools automatically:

ComponentsUpdate where ...
Brokerorg.apache.pulsar.broker.ServiceConfiguration
WebSocketorg.apache.pulsar.websocket.service.WebSocketProxyConfiguration
Proxyorg.apache.pulsar.proxy.server.ProxyConfiguration
Standaloneorg.apache.pulsar.broker.ServiceConfiguration
Clientorg.apache.pulsar.client.impl.conf.ClientConfigurationData
Producerorg.apache.pulsar.client.impl.conf.ProducerConfigurationData
Consumerorg.apache.pulsar.client.impl.conf.ConsumerConfigurationData
Readerorg.apache.pulsar.client.impl.conf.ReaderConfigurationData

Docs for configs of external components (whose source code is hosted outside the Pulsar repositories) are updated manually:

ComponentsUpdate where ...
BookKeeperreference-configuration-bookkeeper.md
Log4jreference-configuration-log4j.md
Log4j shellreference-configuration-log4j-shell.md
ZooKeeperreference-configuration-zookeeper.md

Update command-line tool docs​

Docs for bundled Java-based command-line tools are generated automatically:

ComponentsUpdate where…
pulsarDifferent subcommands of bin/pulsar are updated in different code files
pulsar-adminClasses under the admin command-line folder
pulsar-clientClasses under the client command-line folder
pulsar-perf
  • The websocket-producer subcommand
  • Other subcommands
  • Docs for external command-line tools or bare scripts are updated manually:

    ComponentsUpdate where…
    pulsar-shellpulsar-shell.md
    pulsar-daemonpulsar-daemon.md
    bookkeeperbookkeeper.md

    Update feature matrix​

    Pulsar feature matrix introduces the features supported by language-specific clients and functions. It includes:

    You need to update the feature matrix as soon as your related commits get merged. The workflow is illustrated as follows.

    Client Feature Matrix Workflow

    1. Submit your code and doc PRs.
    2. Get your PRs reviewed and merged.
    3. Update the feature matrix to flag your contribution.
    note