From 8e79315c9f568ba7242efeb65055bb907a189c8c Mon Sep 17 00:00:00 2001
From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com>
Date: Sun, 8 Nov 2026 20:59:05 +0000
Subject: [PATCH 1/2] docs: cover installing v2 and the Python API in the
 migration guide

Add an "Installing v2" section: same PyPI name and command, pinning to stay on v1, other install channels, cpp-linter-action v2 still uses v1, and the smaller Python API (only main()).
---
 docs/docs/migration.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/docs/migration.md b/docs/docs/migration.md
index 94c5f5e3..4397f7e4 100644
--- a/docs/docs/migration.md
+++ b/docs/docs/migration.md
@@ -13,6 +13,7 @@
 [sarif-file]: cli.md#-sarif-file
 [gen-patch-path]: cli.md#-gen-patch-path
 [summary-output-file]: cli.md#-o-summary-output-file
+[quick-start]: index.md#quick-start
 
 # Migrating from v1
 
@@ -20,6 +21,37 @@ This page lists what changes when moving from cpp-linter v1 (the Python package)
 project). Most options keep their names, short flags and meaning, so many command lines work
 unchanged. The sections below cover the differences.
 
+## Installing v2
+
+v2 keeps the package name and the command of v1. On PyPI it is still `cpp-linter`, and it still
+installs a `cpp-linter` command. Once 2.0 is released, `pip install --upgrade cpp-linter` moves to
+v2. To stay on v1, pin the version:
+
+```shell
+pip install "cpp-linter<2"
+```
+
+v2 can also be installed with cargo, as a pre-built binary, or from npm. See
+[Quick start][quick-start] for these commands and for how to install the current release candidate.
+
+cpp-linter-action v2 keeps using cpp-linter v1, so workflows that use the action do not change
+until they move to a new major version of the action.
+
+### Python API
+
+v1 is a Python package, so some scripts import its modules, such as `cpp_linter.rest_api`. The v2
+Python package only provides `cpp_linter.main()`. Scripts that import other v1 modules need to run
+cpp-linter as a command or call `main()` instead. `main()` takes an optional list of strings that
+starts with the program name, like `sys.argv`:
+
+```python
+import cpp_linter
+
+cpp_linter.main(["cpp-linter", "--style=file", "src/main.cpp"])
+```
+
+If cpp-linter fails, `main()` raises an `OSError`.
+
 ## Deprecated options
 
 | v1 option | v2 behavior | What to do |

From 360ba1f445685647440bc79e13bd3081ade22541 Mon Sep 17 00:00:00 2001
From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com>
Date: Sun, 8 Nov 2026 21:04:09 +0000
Subject: [PATCH 2/2] docs: note that invalid arguments exit the Python process

---
 docs/docs/migration.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/docs/migration.md b/docs/docs/migration.md
index 4397f7e4..6e2a7e30 100644
--- a/docs/docs/migration.md
+++ b/docs/docs/migration.md
@@ -50,7 +50,8 @@ import cpp_linter
 cpp_linter.main(["cpp-linter", "--style=file", "src/main.cpp"])
 ```
 
-If cpp-linter fails, `main()` raises an `OSError`.
+If cpp-linter fails, `main()` raises an `OSError`. Invalid arguments and `--help` exit the Python
+process, as they exit the command.
 
 ## Deprecated options