docs(packages): Update README.md

also add the the verify step for the README.md with shelldoc tool Ref: https://github.com/endocode/shelldoc Signed-off-by: wuhuizuo <wuhuizuo@126.com>
PingCAP-QE · Dec 19, 2023 · 4384ad4 · 4384ad4
1 parent c81ae73
commit 4384ad4
Show file tree

Hide file tree

Showing 4 changed files with 64 additions and 11 deletions.
diff --git a/.github/workflows/pull-verify-packages-config.yaml b/.github/workflows/pull-verify-packages-config.yaml
@@ -17,17 +17,32 @@ jobs:
 
       - name: Install tools
         run: |
-          git clone https://github.com/hairyhenderson/gomplate
-          cd gomplate
-          GOBIN=/usr/local/bin go install ./cmd/gomplate
-          rm -rf gomplate
-          gomplate --version
+          # install gomplate
+          git clone https://github.com/hairyhenderson/gomplate && \
+            pushd gomplate && \
+            GOBIN=/usr/local/bin go install ./cmd/gomplate && 
+            popd && 
+            rm -rf gomplate && \
+            gomplate --version
+
+          # install shelldoc to check the README.md
+          git clone https://github.com/endocode/shelldoc && \
+            pushd shelldoc && \
+            GOBIN=/usr/local/bin go install ./cmd/shelldoc && 
+            popd && 
+            rm -rf shelldoc && \
+
+          # we need yq and jq.
           yq --version
           jq --version
 
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Verify the README.md
+        run: |
+          shelldoc run --shell `which bash` packages/README.md
+  
       - name: Test => Get builder
         run: |
           for cm in tidb tiflow tiflash tikv pd; do

diff --git a/packages/README.md b/packages/README.md
@@ -1,2 +1,38 @@
-`WIP`
+Central declarative congfigurations for artifacts delivering. 
 ===
+
+> We use go template format to control them.
+
+## Prerequire tools
+
+- [gomplate](https://github.com/hairyhenderson/gomplate) 
+  > Please install the master version. 
+- [yq]
+- jq
+
+## For component binaries packages and container images
+
+Configuration template: [packages.yaml.tmpl](./packages.yaml.tmpl)
+
+### Required context
+
+You can get them by run:
+```console
+$ grep -oE "{{\s*\..*?}}" packages/packages.yaml.tmpl | grep -oE "\.\w+(\.\w+)*" | sort -u
+.Git.ref
+.Git.sha
+.Release.arch
+.Release.os
+.Release.version
+```
+
+## For offline deploy pacakges
+
+### Required context
+
+You can get them by run:
+```console
+$ grep -oE "{{\s*\..*?}}" packages/offline-packages.yaml.tmpl | grep -oE "\.\w+(\.\w+)*" | sort -u
+.Release.arch
+.Release.version
+```
diff --git a/packages/offline-packages.yaml.tmpl b/packages/offline-packages.yaml.tmpl
@@ -1,11 +1,12 @@
+# See README.md
+artifactory:
+  repo: hub.pingcap.net/pingcap/offline-package
+  tags:
+    - "{{ .Release.version }}"
 artifacts:
   community:
     desc: community offline package
     version: "{{ .Release.version }}" # segment version.
-    artifactory:
-      repo: hub.pingcap.net/pingcap/offline-package
-      tags:
-        - "{{ .Release.version }}"
     routers: # match once.
       - description: "Started from v7.5.0 to latest"
         # ref: https://github.com/Masterminds/semver#checking-version-constraints
@@ -107,7 +108,7 @@ artifacts:
                   extract: true
                   extract_inner_path: "etcd-v3.4.21-linux-{{ .Release.arch }}/etcdctl"
       - description: "Started from v7.1.0 until v7.5"
-          # ref: https://github.com/Masterminds/semver#checking-version-constraints
+        # ref: https://github.com/Masterminds/semver#checking-version-constraints
         if: {{ semver.CheckConstraint ">=7.1.0-0, <7.5.0-0" .Release.version }}
         os: [linux]
         arch: [amd64, arm64]

diff --git a/packages/packages.yaml.tmpl b/packages/packages.yaml.tmpl
@@ -1,3 +1,4 @@
+# See README.md
 components:
   pd:
     desc: pd server component tarball