This is an automated email from the ASF dual-hosted git repository.
lhotari pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new d87f464c6dda Add docs-tool.sh for applying committed docs directory
changes to versioned_docs directory (#972)
d87f464c6dda is described below
commit d87f464c6dda1c86bd87dbd9ae72759c39bcd031
Author: Lari Hotari <[email protected]>
AuthorDate: Thu Oct 31 10:36:46 2024 +0200
Add docs-tool.sh for applying committed docs directory changes to
versioned_docs directory (#972)
* Add script for finding supported versions
* Add docs-tools.sh script for applying doc changes to supported versions
* Add documentation for docs-tool.sh
---
README.md | 13 ++++
contribute/document-contribution.md | 15 +++-
scripts/docs-tool.sh | 149 ++++++++++++++++++++++++++++++++++++
scripts/supported-versions.js | 41 ++++++++++
4 files changed, 214 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index b621a88e5f05..7e893a06c960 100644
--- a/README.md
+++ b/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/)
diff --git a/contribute/document-contribution.md
b/contribute/document-contribution.md
index 62128ab6fe2b..cc24f3e82fb2 100644
--- a/contribute/document-contribution.md
+++ b/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.
:::
```
diff --git a/scripts/docs-tool.sh b/scripts/docs-tool.sh
new file mode 100755
index 000000000000..71fba4f282ca
--- /dev/null
+++ b/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
diff --git a/scripts/supported-versions.js b/scripts/supported-versions.js
new file mode 100644
index 000000000000..b0e228d3af0d
--- /dev/null
+++ b/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(' '));
\ No newline at end of file
