FPSMS-backend/docs/deploy/HOW_TO_GENERATE_COMMIT_TEST_PLANS.md

# How to generate commit test plans (Word)

This guide is for QA / deploy teammates. Use it when a build is ready and you need **what changed** and **how to test** for each commit.

## Easiest: just tell Cursor

In Cursor chat (Agent), say any of:

- `gen test plan`
- `generate test plan for new commits`
- `產測試計畫` / `有新 commit，幫我出 test plan`
- Or use the slash command: **`/gen-commit-test-plans`**

Cursor will run the generator and put Word files in `docs/deploy/commit-plans/`.

You can be more specific:

- `gen test plan for latest commit`
- `gen test plan for HEAD~5..HEAD`
- `gen test plan since abc1234`

---

## What you get

Running the generator creates **one Word file per commit** under:

```
docs/deploy/commit-plans/
  YYYY-MM-DD_<shortsha>_<slug>.docx
  _index.md          ← list of all generated plans
```

Each `.docx` includes:

- Commit id, date, author, message  
- Auto-detected areas (e.g. 送貨出倉, 工單, BOM)  
- Files touched  
- **Test plan table**: Steps + Expected result  

> These plans are a **starting point** (from commit message + file paths). For critical releases, refine steps with the developer or ask the Cursor agent to review the real diff.

---

## Prerequisites

1. Clone / pull latest `FPSMS-backend`.
2. Install Python 3, then:

```bash
pip install python-docx
```

3. Open a terminal at the **repo root** (`FPSMS-backend`).

---

## Basic usage

Generate plans for the last 10 commits:

```bash
python scripts/generate_commit_test_plans_docx.py HEAD~10..HEAD
```

Then open the folder:

```
docs/deploy/commit-plans/
```

Start from `_index.md` to see the list, then open each `.docx`.

---

## Common examples

### Last N commits on current branch

```bash
python scripts/generate_commit_test_plans_docx.py HEAD~5..HEAD
```

### Only the latest commit

```bash
python scripts/generate_commit_test_plans_docx.py HEAD~1..HEAD
```

### Commits since a known SHA (e.g. last production deploy)

```bash
python scripts/generate_commit_test_plans_docx.py <last_deployed_sha>..HEAD
```

Example:

```bash
python scripts/generate_commit_test_plans_docx.py b12b9a49..HEAD
```

### Commits on `production` that are not yet on another branch

```bash
python scripts/generate_commit_test_plans_docx.py origin/staging..origin/production
```

(Adjust branch names to match your remote.)

### Custom output folder

```bash
python scripts/generate_commit_test_plans_docx.py HEAD~10..HEAD --out-dir docs/deploy/commit-plans/release-2026-08-01
```

### Also write Markdown next to Word

```bash
python scripts/generate_commit_test_plans_docx.py HEAD~10..HEAD --also-md
```

### Cap how many commits are processed

```bash
python scripts/generate_commit_test_plans_docx.py HEAD~50..HEAD --limit 15
```

---

## Suggested team workflow

1. Developer merges / tags the build to deploy.  
2. QA or release owner runs the generator for **only the commits in this deploy** (use `last_sha..new_sha`).  
3. Share the `docs/deploy/commit-plans/` folder (or zip it) with testers.  
4. Testers follow Steps / Expected result in each Word file; mark pass/fail.  
5. For vague commits (`no message`), ask the author to clarify before sign-off.  
6. Optional: keep a hand-written summary in `docs/deploy/YYYYMMDD_topic.md` (see `TEMPLATE.md`).

---

## Related files

| File | Purpose |
|------|---------|
| `scripts/generate_commit_test_plans_docx.py` | Auto Word plans **per commit** |
| `scripts/generate_deploy_test_plan.py` | One Markdown scaffold for a **whole range** |
| `docs/deploy/TEMPLATE.md` | Manual deploy / QA note template |
| `docs/deploy/20260727_isextra_truck_x_ticket_fix.md` | Example of a filled manual note |

---

## Troubleshooting

| Problem | What to try |
|---------|-------------|
| `No module named 'docx'` | `pip install python-docx` |
| `No commits in range` | Check the range syntax: `A..B` means commits reachable from B but not from A |
| Word filename looks odd | Filenames are ASCII-only on purpose (Windows-safe). Chinese text is still inside the document |
| Steps look too generic | Commit had `no message` or unusual paths — ask author / refine with agent |
| Need frontend checks | This repo is backend; also check `FPSMS-frontend` if the change is UI |

---

## Quick copy-paste (release day)

```bash
cd /path/to/FPSMS-backend
git fetch
git checkout <deploy-branch>
pip install python-docx
python scripts/generate_commit_test_plans_docx.py <previous_release_sha>..<this_release_sha>
explorer docs\deploy\commit-plans
```

(On Mac/Linux, open `docs/deploy/commit-plans` in Finder/files instead of `explorer`.)