Merge pull request #844 from Gujiassh/docs/helm-chart-versioning-758

docs(helm): clarify chart and app versioning

Author: Pangjiping

kubernetes/charts/opensandbox-server/README.md

@@ -53,6 +53,16 @@ Optional: override gateway image, replicas, or resources (see `server.gateway.*`
 | `server.gateway.gatewayRouteMode` | server config and gateway route mode (header/uri) | `header` |
 | `server.gateway.*` | Gateway image, replicas, port, dataplaneNamespace, providerType, resources | See values.yaml |
 
+Versioning note:
+
+- `server.image.tag` defaults to the chart `appVersion`.
+- The chart package `version` and the image/app `appVersion` are intentionally
+  separate. A server release branch or tag does not automatically imply a new
+  Helm chart package version.
+- If you want the chart to deploy a specific server release, override
+  `server.image.tag` explicitly or consume a Helm package release whose chart
+  version was published for that purpose.
+
 **Gateway**: When `server.gateway.enabled=true`, the chart writes `[ingress] mode = "gateway"` in config.toml and deploys **components/ingress** Deployment/Service/RBAC; gateway `--mode` matches config. External access must be configured separately.
 
 Set `[kubernetes].namespace` in config for the sandbox workload namespace. Override `api_key` via Secret or values in production.

kubernetes/docs/HELM-DEPLOYMENT.md

@@ -449,6 +449,19 @@ This automatically triggers the workflow to:
 4. Create a GitHub Release
 5. Publish the .tgz package to the Release
 
+Important versioning note:
+
+- The Helm chart `version` is the chart package version and is released through
+  `helm/{component}/{version}` tags.
+- The chart `appVersion` is the default image/application version used by that
+  chart release.
+- The `publish-helm-chart.yml` workflow updates `appVersion` for the published
+  release, but intentionally does not auto-bump the chart `version` inside
+  `Chart.yaml` on server release branches.
+- If you need a specific server image release, set the image tag explicitly
+  (for example `--set server.image.tag=v0.1.13`) or publish a new Helm chart
+  package version for the chart itself.
+
 #### Option 2: Manual Trigger
 
 1. Visit the GitHub Actions page