From 39b195709fc5b172489d74bcb7871bce1d32c000 Mon Sep 17 00:00:00 2001
From: Cheese <cheese.javaee@gmail.com>
Date: Mon, 10 Aug 2026 21:37:53 +0800
Subject: [PATCH] docs: add v0.2.0 release notes

---
 docs/release-notes/v0.2.0.md | 73 ++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 docs/release-notes/v0.2.0.md

diff --git a/docs/release-notes/v0.2.0.md b/docs/release-notes/v0.2.0.md
new file mode 100644
index 0000000..4b5886a
--- /dev/null
+++ b/docs/release-notes/v0.2.0.md
@@ -0,0 +1,73 @@
+# TiDB Cloud CLI v0.2.0
+
+This release renames the TiDB Cloud command-line product from `tdc` to `ti` and moves the project to `github.com/tidbcloud/ti-cli`. It also introduces a product-aware database command architecture while keeping the current public database scope limited to TiDB Cloud Starter.
+
+## What's new
+
+- The executable is now `ti`. Commands use forms such as `ti db`, `ti fs`, `ti fs-git`, `ti fs-journal`, and `ti fs-vault`.
+- Installers, release archives, the updater, local state, operation logs, telemetry components, and the bundled filesystem companion now use the `ti` name. The companion is installed as `ti-drive9`.
+- New installations use `~/.ti`, `TI_*` environment variables, and `TIDB_CLOUD_PUBLIC_KEY` / `TIDB_CLOUD_PRIVATE_KEY`.
+- Existing durable v0.1 state can be migrated safely from `~/.tdc` to `~/.ti`. Profiles, credentials, preferences, telemetry identity, SQL credentials, and filesystem registrations are copied; the old directory is never modified or deleted.
+- Database commands now dispatch through product-specific providers. Commands that do not identify an existing cluster require `--db-cluster-type starter`. Commands with `--db-cluster-id` discover the cluster service plan and reject unsupported products before executing an operation.
+- `ti db list-db-clusters --db-cluster-type starter` returns verified Starter clusters from the effective region through bounded, filtered pagination and a `ti`-owned continuation token.
+
+## Upgrade from tdc v0.1.x
+
+This is an intentional breaking change. There is no `tdc` command alias, and the old `tdc update` command cannot install `ti` from the renamed repository.
+
+Before upgrading, drain and unmount every filesystem mounted by `tdc`. Then install `ti` directly.
+
+On macOS or Linux:
+
+```bash
+curl -fsSL https://github.com/tidbcloud/ti-cli/releases/download/v0.2.0/install.sh | sh -s -- --yes
+export PATH="$HOME/.ti/bin:$PATH"
+ti --version
+```
+
+On Windows PowerShell:
+
+```powershell
+$script = "$env:TEMP\install-ti.ps1"
+iwr https://github.com/tidbcloud/ti-cli/releases/download/v0.2.0/install.ps1 -OutFile $script
+powershell -ExecutionPolicy Bypass -File $script -Yes
+$env:Path = "$HOME\.ti\bin;$env:Path"
+ti --version
+```
+
+The installer runs the same migration logic as the CLI. Migration proceeds only when `~/.ti` does not already contain independent state. If both `~/.tdc` and `~/.ti` exist without a valid migration marker, `ti` fails with an actionable conflict instead of merging or overwriting them. Verify the new installation before manually removing old binaries or `~/.tdc`.
+
+Automation should move from `TDC_*` variables to `TI_*`, and from `TDC_PUBLIC_KEY` / `TDC_PRIVATE_KEY` to `TIDB_CLOUD_PUBLIC_KEY` / `TIDB_CLOUD_PRIVATE_KEY`. The v0.2 release line temporarily accepts a legacy variable when its new equivalent is absent; conflicting old and new values fail before any mutation.
+
+## Get started
+
+Configure a profile:
+
+```bash
+ti configure
+```
+
+Create and query a Starter cluster:
+
+```bash
+CLUSTER_ID="$(ti db create-db-cluster --db-cluster-type starter --db-cluster-name my-app-db --wait --query id --output text)"
+ti db create-db-sql-users --db-cluster-id "$CLUSTER_ID"
+ti db execute-sql-statement --db-cluster-id "$CLUSTER_ID" --read-write --sql "SELECT 1"
+```
+
+Create and mount a TiDB Cloud Filesystem:
+
+```bash
+ti fs create-file-system --file-system-name workspace --wait
+mkdir -p "$HOME/workspace"
+ti fs mount-file-system --file-system-name workspace --mount-path "$HOME/workspace"
+```
+
+Future upgrades use the new updater:
+
+```bash
+ti update --check
+ti update
+```
+
+The v0.1 `tdc` release line is no longer updated.