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.
# List all supported major.minor.x versions
./scripts/docs-tool.sh 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.
After committing the changes for the docs directory, you can use the docs-tool to apply the changes to the versioned docs. This tool is a wrapper around git diff and patch. If the patch is not applied correctly, you will have to manually apply the changes to the versioned docs.
./scripts/docs-tool.sh apply_changes_to_versioned_docs
For example, if you want to add docs for an improvement introduced in 4.0.1, you can add the following instructions:
:::note
This <fix / improvment> is available for 4.0.1 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:
Docs for configs of external components (whose source code is hosted outside the Pulsar repositories) are updated manually:
| Components | Update where ... |
|---|---|
| BookKeeper | reference-configuration-bookkeeper.md |
| Log4j | reference-configuration-log4j.md |
| Log4j shell | reference-configuration-log4j-shell.md |
| ZooKeeper | reference-configuration-zookeeper.md |
Update command-line tool docs
Docs for bundled Java-based command-line tools are generated automatically:
| Components | Update where… |
|---|---|
| pulsar | Different subcommands of bin/pulsar are updated in different code files |
| pulsar-admin | Classes under the admin command-line folder |
| pulsar-client | Classes under the client command-line folder |
| pulsar-perf | websocket-producer subcommand |
Docs for external command-line tools or bare scripts are updated manually:
| Components | Update where… |
|---|---|
| pulsar-shell | pulsar-shell.md |
| pulsar-daemon | pulsar-daemon.md |
| bookkeeper | bookkeeper.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.
- Submit your code and doc PRs.
- Get your PRs reviewed and merged.
- Update the feature matrix to flag your contribution.
- For how to update the Client Feature Matrix, see How to update data-driven pages.
- If you have problems in editing the spreadsheet of Function Feature Matrix, you can reach out to
dev@pulsar.apache.org.