PIP-190: Simplify documentation release and maintenance strategy

[momo-jun]

• Status: Accepted/Implemented
• Author: momo-jun
• Pull Request: #16938, update versions page and upgrade docusaurus to 2.0.1 pulsar-site#157
• Mailing List discussion: Discussion, Vote
• Release: applies to 2.8.x and later versions

Motivation

This proposal is focused on improving and simplifying the release and maintenance strategy of the existing Apache Pulsar documentation.

In general, this proposal provides equal values and a better user experience without making overwhelming sacrifices in the release and maintenance process. The benefits include:

• Improve user experience when they look for the documentation of a specific release.
• Optimize the doc development and release process for bug-fix releases:
  • Turn doc development for bug-fix releases from post-release into just-in-time.
  • Save Release Manager’s effort in generating doc files for bug-fix releases.
• Save a great amount of the community’s effort in syncing doc improvements and fixes to historical doc versions that are in the maintenance cycle.

Summary of the current strategy and activities

Pulsar version number is comprised of 3 components: major.minor.bug-fix. See definition.

The current practice of the Pulsar documentation is releasing and maintaining individual versions of documentation for each bug-fix releases, including:

1. The Release Manager needs to generate doc-related files for each bug-fix release. ----This activity is canceled in this proposal.
2. The doc development for bug-fix releases can only be implemented after a release (due to item1). ----This activity can be turned into just-in-time doc development in this proposal.
   1. The labeling process of bug-fix releases usually happens after a PR is merged. When a contributor submits a PR to change docs, he/she usually changes the doc in the master branch only, because he/she doesn’t know which release the change will be included.
   2. The doc development for bug-fix releases has a dependency on the release of the new doc version. It requires someone to manually catch up with the doc changes for bug-fix releases after the doc set is generated by the Release Manager. What’s worse, this action is sometimes missed.
3. The community keeps updating all the doc versions (15+) that are in the maintenance cycle. ---- This activity can be narrowed down to 4 doc versions in this proposal.
4. Users have to go through an endless list when they want to look for the documentation of a specific release.

Proposal

1. Maintain doc sets for the last 4 feature releases

Pulsar is evolving very fast and generally has a 3-month release cycle, that is, 4 feature releases per year (sometimes 3 feature releases), with even more bug-fix versions. There is a high cost to maintain a lot of old releases, backport bug fixes, and security patches. In general, the last 4 feature releases are actively supported while the next feature release is being developed. For example, the community provides feature releases for 2.7, 2.8, 2.9, and 2.10, while 2.11 is under development. See PIP-47 for more details.

Accordingly, this proposal includes the first attempt to establish the doc maintenance strategy aligned with code, that is, we only keep maintaining doc sets for the last 4 feature releases: 2.7.x, 2.8.x, 2.9.x, and 2.10.x, while 2.11.0 is under development.

2. Release one doc version for each feature release and bug-fix release behind

The proposal introduces a simplified strategy for releasing and maintaining an all-in-one doc version for each feature release and more bug-fix releases behind it, as shown below.

Doc version page mockup

The following diagram shows the mockup of how the information architecture for the Pulsar doc version page can be simplified with clarity for entry.

The key change on this page is about the fewer, simplified menus and links for documentation, and this new structure is also easier to maintain and scale.

Note: This is a mockup to demo the BEFORE & AFTER. When it comes to implementation, we need to make a compromise to only apply the strategy to doc sets for 2.8.x and later versions by balancing the workload differences.

Compare outcomes

The biggest difference between the proposal and the current practice is the strategy of releasing docs for bug-fix releases, and the outcome is compared in the following diagram.

Just-in-time doc development for bug-fix releases

As one of the outcomes, just-in-time doc development for bug-fix releases is feasible with the following facts taken into consideration.

Facts

• The latest stable doc set for the feature release is up and running, like 2.10.x. As soon as a few doc PRs are labeled for a bug-fix version (2.10.1), the related doc changes can be implemented right away on top of 2.10.x doc set. The dependency with generating a new version of the doc set no longer exists.
• Doc changes for improvements in bug-fix releases are limited (less than 10 PRs per version) based on previous releases. Take 2.10.1 for example:

Proposed solution
Add an additional annotation like “This enhancement is only available for 2.10.1 and later versions.” for enhancements with doc requests in each bug-fix release. This needs to be added to the Contribution Guide.

Implementation plan

Apply the strategy to 2.8.x and later versions of documentation

By balancing the predictable workload introduced by the proposal and the unpredictable maintenance effort using the current strategy, we have to make a compromise that we only apply the strategy to 2.8.x and later versions.

The actions to change these versions of docs sets include:

1. Add annotation for 2.M.1~2.M.n-specific doc changes to the 2.M.x docs(M⪰8)
2. Rename versioned-docs/2.M.0 to versioned-docs/2.M.x
3. Remove versioned-docs/2.M.1~2.M.n from the Pulsar repo

Update the doc version page

Use 2.10.x as the latest doc version and refresh the information for 2.8.x and 2.9.x.

Update the release document

Remove the section of Update the site for minor releases.
Note that the minor releases mentioned in this section actually refer to bug-fix releases according to the version number definition in PIP-47.

The reason is Release Managers will not need to generate documentation and update the doc site for bug-fix releases. Take 2.10.1 for example, they can skip the following pull requests and much more effort in their local processing.

Note: The release notes for bug-fix releases are still required.

Update the contribution guide

Update the doc contribution guide to clarify the standard processing for the doc changes in bug-fix releases.

[Anonymitaet]

Thanks for your contribution! I've left some comments, PTAL. Feel free to let me know if you have any concerns. 😊

[momo-jun]

@Anonymitaet can you pls help update the release document and contribution guide? Both the new doc sets 2.8.x/2.9.x/2.10.x and the new versions page are in place.

[Anonymitaet]

@momo-jun sure, I'll do that and request your review.

[tisonkun]

Now we encounter a new issue that the version number is 2.10.x so all the placeholder @pulsar:version_number@ becomes 2.10.x. It will generate some fake info:

We only provide 2.10.0 or 2.10.1, no 2.10.x.

[tisonkun]

One more fake: all these links to maven central are broken links due to we don't publish version exact 2.10.x

[momo-jun]

@tisonkun Thanks for the finding.

Two placeholders @pulsar:version@ and @pulsar:version_number@ are widely used in a dozen of doc pages in terms of:

• Static text - maybe add a tip/note to notify users to instantiate the version number.
• Links to REST APIs - can we use the latest instance of X to generate REST APIs to serve the purpose? @urfreespace
• Links to Maven - users can continue to select a specific version number there, which is not bad. Any better ideas?

[momo-jun]

Two placeholders @pulsar:version@ and @pulsar:version_number@ are widely used in a dozen of doc pages in terms of:

• Static text - maybe add a tip/note to notify users to instantiate the version number.
• Links to REST APIs - can we use the latest instance of X to generate REST APIs to serve the purpose? @urfreespace
• Links to Maven - users can continue to select a specific version number there, which is not bad. Any better ideas?

Many thanks to @urfreespace for providing a resolution/patch to fix the issue, which covers all the above three categories.

[momo-jun]

Closed the issue since the PIP has been implemented.

[tisonkun]

@momo-jun @Anonymitaet is it possible to name the doc version as 2.11 instead of 2.11.x and ditto for the following new versions? I don't think it's a brand new proposal here but a .x brings unnecessary confusion from my perspective.

For example:

• https://hbase.apache.org/2.4/book.html
• https://nightlies.apache.org/flink/flink-docs-release-1.15/

I agree it's a good idea to merge patch releases into one URL since no significant changes would be made. I'm glad to know whether there're other projects using .x versions in the docs site and URL and see how it works.

UPDATE: I found Kafka name versions with a .x suffix but not in the main content or in the URL. https://kafka.apache.org/24/documentation.html

[Anonymitaet]

@tisonkun thank you!

🔹🔹🔹

Here are some similar cases to Pulsar (use .x in doc management and URL)

• Kong docs

• RocketMQ

🔹🔹🔹

Here are some similar cases to Kafka (use .x in doc management but not in URL)

• Kubesphere

• Docusaurus

🔹🔹🔹

I think 2.11.x is OK since .x is commonly used and everyone may know the meaning at the 1st glance.

@D-2-Ed @DaveDuggins @momo-jun thoughts?

[tisonkun]

@Anonymitaet Thanks for your information! This makes many sense.