Add docs-tool.sh for applying committed docs directory changes to versioned_docs directory

README.md

@@ -16,8 +16,21 @@ To preview the changes, run the following command ([prerequisites](https://pulsa
 
 This command starts a local web server on port 3000 and opens a browser window pointing to the website.
 
+### Updating versioned docs
+
 When your documentation changes apply to existing [supported versions](https://pulsar.apache.org/contribute/release-policy/#supported-versions), you should update both the versioned documentation in the `versioned_docs` directory and the documentation in the `docs` directory.
 
+```shell
+# List all supported major.minor.x versions
+./scripts/docs-tool.sh supported_versions
+```
+
+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.
+
+```shell
+./scripts/docs-tool.sh apply_changes_to_versioned_docs
+```
+
 ## More information
 
 * [Pulsar Website contribution guide](https://pulsar.apache.org/contribute/site-intro/)

contribute/document-contribution.md

@@ -13,20 +13,27 @@ Currently, the source of documents and website (where the docs are finally publi
 
 Documentation should be up to date for all [actively supported versions](https://pulsar.apache.org/contribute/release-policy/#supported-versions).
 
+```shell
+# 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](https://github.com/apache/pulsar-site/tree/main/versioned_docs).
 
-For versions prior to 2.8, Pulsar releases versioned docs for each patch release. You can update the exact versioned doc.
+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.
 
-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.
+```shell
+./scripts/docs-tool.sh apply_changes_to_versioned_docs
+```
 
-For example, if you want to add docs for an improvement introduced in 2.8.2, you can add the following instructions:
+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 2.8.2 and later versions.
+This <fix / improvment> is available for 4.0.1 and later versions.
 
 :::
 ```

scripts/docs-tool.sh

@@ -0,0 +1,149 @@
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && pwd)"
+supported_versions=$(node $SCRIPT_DIR/supported-versions.js)
+UPSTREAM="${UPSTREAM:-origin}"
+
+# Add these color definitions at the top of the file after UPSTREAM declaration
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Add this after the color definitions
+if [ -t 1 ]; then
+  # Terminal supports colors
+  :
+else
+  # No color support - reset all colors to empty strings
+  RED=''
+  GREEN=''
+  YELLOW=''
+  BLUE=''
+  NC=''
+fi
+
+function _cd_git_root() {
+    cd $SCRIPT_DIR/..
+}
+
+function docs_apply_patch_to_versioned_docs() {
+  (
+    if [[ "$1" == "--desc" || "$1" == "--help" ]]; then
+      echo "Applies a patch file to versioned docs"
+      if [ "$1" == "--help" ]; then
+        echo "usage: $0 apply_patch_to_versioned_docs [--strip-count N] patchfile"
+      fi
+      return 0
+    fi
+    local patch_strip_count=2
+    if [[ "$1" == "--strip-count"  ]]; then
+      shift
+      patch_strip_count="$1"
+      shift
+    fi
+    local patchfile="${1:?Patch file is required}"
+    shift
+    _cd_git_root
+    cd versioned_docs
+    for version in $supported_versions; do
+      local version_dir="version-${version}"
+      cd "$version_dir"
+      echo "Applying patch to $version_dir"
+      patch -f -N -V none -p$patch_strip_count < "$patchfile" || echo "Failed to apply patch to $version_dir"
+      cd ..
+    done
+  )
+}
+
+function docs_apply_last_commit_to_versioned_docs() {
+  (
+    if [[ "$1" == "--desc" || "$1" == "--help" ]]; then
+      echo "Applies the patch based on the most recent commit to versioned docs"
+      if [ "$1" == "--help" ]; then
+        echo "usage: $0 apply_last_commit_to_versioned_docs"
+      fi
+      return 0
+    fi
+    _cd_git_root
+    local patchfile=$(mktemp)
+    git diff -u HEAD~1 -- docs/ > "$patchfile"
+    docs_apply_patch_to_versioned_docs "$patchfile" "$@"
+  )
+}
+
+function docs_apply_changes_to_versioned_docs() {
+  (
+    if [[ "$1" == "--desc" || "$1" == "--help" ]]; then
+      echo "Applies committed changes made to docs directory between current branch and upstream main to versioned docs"
+      if [ "$1" == "--help" ]; then
+        echo "usage: $0 apply_changes_to_versioned_docs"
+      fi
+      return 0
+    fi
+    _cd_git_root
+    local patchfile=$(mktemp)
+    git diff -u $(git merge-base HEAD $UPSTREAM/main) -- docs/ > "$patchfile"
+    docs_apply_patch_to_versioned_docs "$patchfile" "$@"
+  )
+}
+
+function docs_delete_patch_backups() {
+  (
+    if [[ "$1" == "--desc" || "$1" == "--help" ]]; then
+      echo "Deletes patch backup files"
+      if [ "$1" == "--help" ]; then
+        echo "usage: $0 delete_patch_backups"
+      fi
+      return 0
+    fi
+    _cd_git_root
+    find '(' -name "*.rej" -or -name "*.orig" ')' -delete
+  )
+}
+
+function docs_supported_versions() {
+  if [[ "$1" == "--desc" || "$1" == "--help" ]]; then
+    echo -e "${BLUE}Lists all supported versions${NC}"
+    if [ "$1" == "--help" ]; then
+      echo -e "usage: $0 ${GREEN}supported_versions${NC}"
+    fi
+    return 0
+  fi
+  echo $supported_versions
+}
+
+# lists all available functions in this tool
+function docs_list_functions() {
+  if [[ "$1" == "--desc" || "$1" == "--help" ]]; then
+    echo -e "${BLUE}Lists all available functions in this tool${NC}"
+    if [ "$1" == "--help" ]; then
+      echo -e "usage: $0 ${GREEN}list_functions${NC}"
+    fi
+    return 0
+  fi
+  for function_name in $(declare -F | awk '{print $NF}' | sort | egrep '^docs_' | sed 's/^docs_//'); do
+    printf "${GREEN}%-20s${NC}\t%s\n" $function_name "$(eval "docs_${function_name}" --desc)"
+  done  
+}
+
+if [ -z "$1" ]; then
+  echo -e "${BLUE}docs tool${NC}"
+  echo -e "usage: $0 ${GREEN}[docs_tool_function_name]${NC} [arguments]"
+  echo -e "Pass ${YELLOW}--help${NC} as the argument to get usage information for a tool."  
+  echo ""
+  echo -e "${BLUE}Available docs tool functions:${NC}"
+  docs_list_functions
+  exit 1
+fi
+docs_function_name="docs_$1"
+shift
+
+if [[ "$(LC_ALL=C type -t "${docs_function_name}")" == "function" ]]; then
+  eval "$docs_function_name" "$@"
+else
+  echo -e "${RED}Invalid docs tool function${NC}"
+  echo -e "${BLUE}Available docs tool functions:${NC}"
+  docs_list_functions
+  exit 1
+fi

scripts/supported-versions.js

@@ -0,0 +1,41 @@
+const releases = require('../data/release-pulsar.js');
+const moment = require('moment');
+const semver = require('semver/preload');
+
+function resolveActiveSupport(ver, released) {
+  const support = moment(released);
+
+  if (ver.compareMain('3.0.0') < 0) {
+    return support.add(12, 'months');
+  } else if (ver.minor > 0) {
+    return support.add(6, 'months');
+  } else {
+    return support.add(24, 'months');
+  }
+}
+
+function getSupportedVersionBranches(releases) {
+  const releaseList = releases
+    .map(r => ({
+      version: semver.coerce(r.tagName),
+      released: moment(r.publishedAt)
+    }));
+
+  const now = moment();
+  const supportedVersions = releaseList
+    .filter(release => {
+        if (release.version.patch === 0) {
+            const supportEnd = resolveActiveSupport(release.version, release.released);
+            return supportEnd.isAfter(now);
+        } else {
+            return false;
+        }
+    })
+    .sort((a, b) => semver.rcompare(b.version, a.version))
+    .map(release => `${release.version.major}.${release.version.minor}.x`);
+
+  return supportedVersions;
+}
+
+const supported = getSupportedVersionBranches(releases);
+console.log(supported.join(' '));