Skip to content

docs(helm): Add Helm chart downloading steps to the quick start guide; Rename the quick start "Overview" page as "First steps" for clarity.#1887

Merged
junhaoliao merged 6 commits into
y-scope:mainfrom
junhaoliao:helm-docs-plus
Jan 20, 2026

Conversation

@junhaoliao

@junhaoliao junhaoliao commented Jan 20, 2026

Copy link
Copy Markdown
Member

Description

As the title says, this PR aims to narrow the gap for readers unfamiliar with the project.

Checklist

  • The PR satisfies the contribution guidelines.
  • This is a breaking change and that has been indicated in the PR title, OR this isn't a
    breaking change.
  • Necessary docs have been updated, OR no docs need to be updated.

Validation performed

task docs:serve and confirmed in the browser that the docs are modified as expected.

Summary by CodeRabbit

  • Documentation
    • Quick-start Helm guides updated to download-and-extract the deployment package before running helm install (replaces direct cd into local package).
    • Applied the download-and-prepare workflow to both JSON and text quick-start pages.
    • Renamed quick-start top-level section from "Overview" to "First steps" for clearer orientation.

✏️ Tip: You can customize this high-level summary in your review settings.

@junhaoliao junhaoliao requested a review from a team as a code owner January 20, 2026 00:01
@coderabbitai

coderabbitai Bot commented Jan 20, 2026

Copy link
Copy Markdown
Contributor

Walkthrough

Updated quick-start docs to download and extract the Helm chart tarball into $HOME/clp-package-helm and cd into the extracted chart before running helm install; renamed the quick-start top-level header to "First steps". (33 words)

Changes

Cohort / File(s) Summary
Helm packaging and install (JSON doc)
docs/src/user-docs/quick-start/clp-json.md
Replaced direct cd tools/deployment/package-helm with a download-and-extract flow that creates $HOME/clp-package-helm, downloads the repo tarball, extracts clp-DOCS_VAR_CLP_GIT_REF/tools/deployment/package-helm into it, then cds into that directory; helm install block preserved.
Helm packaging and install (Text doc)
docs/src/user-docs/quick-start/clp-text.md
Same change as above: substitute local cd with download-and-extract into $HOME/clp-package-helm, then cd into extracted chart; helm install preserved.
Quick-start header rename
docs/src/user-docs/quick-start/index.md
Renamed top-level header from "Overview" to "First steps".

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes both main changes: adding Helm chart downloading steps and renaming the Overview page to First steps.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Comment thread docs/src/user-docs/quick-start/clp-json.md Outdated
Comment thread docs/src/user-docs/quick-start/clp-text.md Outdated
@junhaoliao junhaoliao self-assigned this Jan 20, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/src/user-docs/quick-start/index.md (1)

54-78: Add Git to Kubernetes system requirements.

The updated Kubernetes quick-start workflow now requires users to clone the repository (as seen in clp-json.md lines 101-102 and clp-text.md lines 111-112), but Git is not listed in the system requirements.

📝 Suggested addition to system requirements

Add Git to the requirements list and verification commands:

 [`kind`][kind] (Kubernetes in Docker) runs a Kubernetes cluster inside Docker containers, making it
 ideal for local Kubernetes testing and development.
 
 * [Docker][Docker] (required for `kind`)
   * `containerd.io` >= 1.7.18
   * `docker-ce` >= 27.0.3
   * `docker-ce-cli` >= 27.0.3
 * [`kind`][kind] >= 0.23
 * [`kubectl`][kubectl] >= 1.30
 * [Helm][Helm] >= 4.0
+* [Git][Git]
 
 To check whether the required tools are installed on your system, run:
 
 ```bash
 containerd --version
 docker version --format '{{.Server.Version}}'
 kind version
 kubectl version --client --output=yaml | grep gitVersion
 helm version --short
+git --version

Then add the Git reference link at the bottom of the file alongside the other reference links.
</details>

</blockquote></details>

</blockquote></details>
🤖 Fix all issues with AI agents
In `@docs/src/user-docs/quick-start/clp-json.md`:
- Around line 101-104: The cloning instruction is ambiguous; update the text
around the git clone and cd lines so it is explicit: either remove "(if you
haven't already)" and state a single step that users should run to clone the
repo (the line starting with "git clone --branch DOCS_VAR_CLP_GIT_REF ..."), or
rewrite to handle both cases by adding a short conditional note that if the repo
is already cloned, skip the git clone step and otherwise run it, and ensure the
following "cd clp/tools/deployment/package-helm" step clearly references the
cloned repo directory (i.e., instruct users to cd into the cloned repository
root first if they ran the clone). Ensure the updated content keeps the existing
git clone and cd commands but clarifies the user flow.
♻️ Duplicate comments (1)
docs/src/user-docs/quick-start/clp-text.md (1)

111-114: Clarify the repository cloning instruction.

The comment "(if you haven't already)" is confusing since this is the first mention of cloning in the quick-start workflow. Additionally, the conditional phrasing doesn't align well with the subsequent cd command, which assumes the repository was cloned to the default location.

✏️ Suggested clarification
-# Clone the repository (if you haven't already)
+# Clone the repository and navigate to the Helm chart directory
 git clone --branch DOCS_VAR_CLP_GIT_REF https://github.com/y-scope/clp.git
 cd clp/tools/deployment/package-helm

Alternatively, if you want to accommodate users who may have already cloned:

-# Clone the repository (if you haven't already)
-git clone --branch DOCS_VAR_CLP_GIT_REF https://github.com/y-scope/clp.git
-cd clp/tools/deployment/package-helm
+# Clone the repository
+git clone --branch DOCS_VAR_CLP_GIT_REF https://github.com/y-scope/clp.git
+
+# Navigate to the Helm chart directory
+cd clp/tools/deployment/package-helm

Comment on lines +101 to +104
# Clone the repository (if you haven't already)
git clone --branch DOCS_VAR_CLP_GIT_REF https://github.com/y-scope/clp.git
cd clp/tools/deployment/package-helm

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Clarify the repository cloning instruction.

The comment "(if you haven't already)" is confusing since this is the first mention of cloning in the quick-start workflow. Additionally, the conditional phrasing doesn't align well with the subsequent cd command, which assumes the repository was cloned to the default location.

✏️ Suggested clarification
-# Clone the repository (if you haven't already)
+# Clone the repository and navigate to the Helm chart directory
 git clone --branch DOCS_VAR_CLP_GIT_REF https://github.com/y-scope/clp.git
 cd clp/tools/deployment/package-helm

Alternatively, if you want to accommodate users who may have already cloned:

-# Clone the repository (if you haven't already)
-git clone --branch DOCS_VAR_CLP_GIT_REF https://github.com/y-scope/clp.git
-cd clp/tools/deployment/package-helm
+# Clone the repository
+git clone --branch DOCS_VAR_CLP_GIT_REF https://github.com/y-scope/clp.git
+
+# Navigate to the Helm chart directory
+cd clp/tools/deployment/package-helm
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# Clone the repository (if you haven't already)
git clone --branch DOCS_VAR_CLP_GIT_REF https://github.com/y-scope/clp.git
cd clp/tools/deployment/package-helm
# Clone the repository and navigate to the Helm chart directory
git clone --branch DOCS_VAR_CLP_GIT_REF https://github.com/y-scope/clp.git
cd clp/tools/deployment/package-helm
🤖 Prompt for AI Agents
In `@docs/src/user-docs/quick-start/clp-json.md` around lines 101 - 104, The
cloning instruction is ambiguous; update the text around the git clone and cd
lines so it is explicit: either remove "(if you haven't already)" and state a
single step that users should run to clone the repo (the line starting with "git
clone --branch DOCS_VAR_CLP_GIT_REF ..."), or rewrite to handle both cases by
adding a short conditional note that if the repo is already cloned, skip the git
clone step and otherwise run it, and ensure the following "cd
clp/tools/deployment/package-helm" step clearly references the cloned repo
directory (i.e., instruct users to cd into the cloned repository root first if
they ran the clone). Ensure the updated content keeps the existing git clone and
cd commands but clarifies the user flow.

@kirkrodrigues kirkrodrigues left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, just realized something.

```bash
cd tools/deployment/package-helm
# Clone the repository (if you haven't already)
git clone --branch DOCS_VAR_CLP_GIT_REF https://github.com/y-scope/clp.git

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we read the guide from the top, then we're going to create the data directories in $HOME/clp. Then we're going to clone the repository into ./clp. If the user hasn't changed directories from ~, then this will also be where the data directories already exist, right? Should we perhaps make the user create the data into something like $HOME/clp-data? That would also make it more obvious that it's data and shouldn't be blindly deleted.

@junhaoliao junhaoliao changed the title docs(helm): Add repository cloning steps to the quick start guide; Rename the quick start "Overview" page as "First steps" for clarity. docs(helm): Add Helm chart downloading steps to the quick start guide; Rename the quick start "Overview" page as "First steps" for clarity. Jan 20, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Fix all issues with AI agents
In `@docs/src/user-docs/quick-start/clp-text.md`:
- Around line 111-117: The curl->tar pipeline (the line starting with "curl
--silent \") can hide HTTP errors and lead to confusing tar errors; update the
pipeline to enable failure visibility by adding curl flags --fail and
--show-error (so curl exits non‑zero on HTTP errors and prints messages) and
ensure the shell exits on pipeline failures (enable set -o pipefail or set -euo
pipefail before the commands) or explicitly check curl's exit status before
piping to tar; keep the existing tar invocation ("tar --extract --gzip
--strip-components=4 --directory \"$HOME/clp-package-helm\"") but only run it
after confirming the download succeeded.

Comment on lines +103 to +104
curl --silent \
--location https://github.com/y-scope/clp/archive/refs/heads/DOCS_VAR_CLP_GIT_REF.tar.gz \

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
curl --silent \
--location https://github.com/y-scope/clp/archive/refs/heads/DOCS_VAR_CLP_GIT_REF.tar.gz \
curl \
--silent \
--location https://github.com/y-scope/clp/archive/refs/heads/DOCS_VAR_CLP_GIT_REF.tar.gz \

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Fix all issues with AI agents
In `@docs/src/user-docs/quick-start/clp-json.md`:
- Around line 101-112: The document includes verbose procedural extraction steps
(the curl/tar sequence that creates "$HOME/clp-package-helm" and extracts
"clp-DOCS_VAR_CLP_GIT_REF/tools/deployment/package-helm"); trim this by
replacing the full command block with a short conceptual summary (e.g.,
"download and extract the Helm chart into a local directory") and add a clear
link to the detailed step‑by‑step video or external guide for users who need
exact commands, keeping only one-line notes about prerequisites (like ensuring
curl/tar are installed) and the target path.

In `@docs/src/user-docs/quick-start/clp-text.md`:
- Around line 111-122: The detailed step-by-step extraction block (the
mkdir/curl | tar pipeline that creates "$HOME/clp-package-helm" and extracts
"clp-DOCS_VAR_CLP_GIT_REF/tools/deployment/package-helm") should be shortened to
a one-line conceptual instruction and a link to the procedural video/resource;
move the full command sequence into a linked appendix or external gist/how-to
page and replace the current lines with a brief summary like "Download and
extract the Helm chart (see video/appendix for commands)". Ensure the summary
references the target folder name ("$HOME/clp-package-helm") and the package
path ("clp-DOCS_VAR_CLP_GIT_REF/tools/deployment/package-helm") so readers can
find the full commands in the linked resource.
♻️ Duplicate comments (2)
docs/src/user-docs/quick-start/clp-text.md (1)

111-122: Handle download failures explicitly in the curl→tar pipeline.

This mirrors a previously raised concern: without --fail --show-error (or equivalent) and pipefail behaviour, HTTP failures are easy to miss and tar errors become confusing. Please align with the earlier review comment for this block.

docs/src/user-docs/quick-start/clp-json.md (1)

101-112: Handle download failures explicitly in the curl→tar pipeline.

Same issue as previously noted: curl --silent in a pipe can mask HTTP errors; add explicit failure visibility/pipefail per prior review guidance.

Comment on lines +101 to +112
# Download and extract the Helm chart from the CLP repository.
mkdir -p "$HOME/clp-package-helm"
curl \
--silent \
--location https://github.com/y-scope/clp/archive/refs/heads/DOCS_VAR_CLP_GIT_REF.tar.gz \
| tar \
--extract \
--gzip \
--strip-components=4 \
--directory "$HOME/clp-package-helm" \
"clp-DOCS_VAR_CLP_GIT_REF/tools/deployment/package-helm"
cd "$HOME/clp-package-helm"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Consider moving detailed extract steps to a linked video or a brief summary.

This level of procedural detail conflicts with the team preference to keep docs conceptual and rely on video for step-by-step actions. Consider trimming and linking out. Based on learnings, ...

🤖 Prompt for AI Agents
In `@docs/src/user-docs/quick-start/clp-json.md` around lines 101 - 112, The
document includes verbose procedural extraction steps (the curl/tar sequence
that creates "$HOME/clp-package-helm" and extracts
"clp-DOCS_VAR_CLP_GIT_REF/tools/deployment/package-helm"); trim this by
replacing the full command block with a short conceptual summary (e.g.,
"download and extract the Helm chart into a local directory") and add a clear
link to the detailed step‑by‑step video or external guide for users who need
exact commands, keeping only one-line notes about prerequisites (like ensuring
curl/tar are installed) and the target path.

Comment on lines +111 to +122
# Download and extract the Helm chart from the CLP repository.
mkdir -p "$HOME/clp-package-helm"
curl \
--silent \
--location https://github.com/y-scope/clp/archive/refs/heads/DOCS_VAR_CLP_GIT_REF.tar.gz \
| tar \
--extract \
--gzip \
--strip-components=4 \
--directory "$HOME/clp-package-helm" \
"clp-DOCS_VAR_CLP_GIT_REF/tools/deployment/package-helm"
cd "$HOME/clp-package-helm"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Consider moving detailed extract steps to a linked video or a brief summary.

These lines introduce step-by-step extraction details. Team preference is to keep written docs conceptual and use video for procedural walkthroughs; consider shortening this block and linking to a video/resource. Based on learnings, ...

🤖 Prompt for AI Agents
In `@docs/src/user-docs/quick-start/clp-text.md` around lines 111 - 122, The
detailed step-by-step extraction block (the mkdir/curl | tar pipeline that
creates "$HOME/clp-package-helm" and extracts
"clp-DOCS_VAR_CLP_GIT_REF/tools/deployment/package-helm") should be shortened to
a one-line conceptual instruction and a link to the procedural video/resource;
move the full command sequence into a linked appendix or external gist/how-to
page and replace the current lines with a brief summary like "Download and
extract the Helm chart (see video/appendix for commands)". Ensure the summary
references the target folder name ("$HOME/clp-package-helm") and the package
path ("clp-DOCS_VAR_CLP_GIT_REF/tools/deployment/package-helm") so readers can
find the full commands in the linked resource.

@junhaoliao junhaoliao merged commit 1843abd into y-scope:main Jan 20, 2026
9 checks passed
@junhaoliao junhaoliao deleted the helm-docs-plus branch May 7, 2026 19:46
junhaoliao added a commit to junhaoliao/clp that referenced this pull request May 17, 2026
…; Rename the quick start "Overview" page as "First steps" for clarity. (y-scope#1887)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants