--- name: bot-api-update description: Implement support for a new Telegram Bot API version in this package. Use when asked to update the library to a new Bot API version. --- # Telegram Bot API version update Port a new Telegram Bot API release into this package, end to end. Read `AGENTS.md` before writing any code — it holds the layout, class shapes, test patterns and changelog rules the resulting diff is judged by. When in doubt, open a class added by the previous Bot API commit (`git log --oneline --grep='Telegram Bot API'`) and copy its shape. Copy the *shape* only, never the location: older commits still put new classes into the legacy subdirectories (`src/Method/UpdatingMessage/DeleteEphemeralMessage.php`, `src/Type/Payment/BotSubscriptionUpdated.php`). Where a file goes is decided by `AGENTS.md` alone — every new type lands in `src/Type`, every new method in `src/Method`. ## 1. Repository state ```bash git status --porcelain # must be empty git branch --show-current git fetch origin ``` A dirty working tree stops the skill: report it and ask the user what to do. If the current branch is already a Bot API branch (`apiXY`) started from the current `origin/master` tip, stay on it and continue from wherever it left off — do not switch, do not create a new branch, and skip to the first unfinished item of `runtime/bot-api-update/plan.md`. Otherwise take the fresh `master` tip; the branch itself is created in step 3, once the target version is known: ```bash git switch master git pull --ff-only origin master ``` ## 2. Download the official pages Everything this skill downloads or generates lives in `runtime/bot-api-update/` — `runtime/` is fully gitignored, and the own subdirectory keeps these files apart from the other tools' output. ```bash mkdir -p runtime/bot-api-update curl -fsS -o runtime/bot-api-update/api-changelog.html https://core.telegram.org/bots/api-changelog curl -fsS -o runtime/bot-api-update/api.html https://core.telegram.org/bots/api python3 .claude/skills/bot-api-update/scripts/telegram_page_to_md.py \ runtime/bot-api-update/api-changelog.html runtime/bot-api-update/api-changelog.md python3 .claude/skills/bot-api-update/scripts/telegram_page_to_md.py \ runtime/bot-api-update/api.html runtime/bot-api-update/api.md ``` `api-changelog.md` says *what* changed; `api.md` (the full reference, several thousand lines — grep it, never read it whole) gives the exact field names, types and optionality needed to write the classes. Each type and method is a `#### ` heading followed by one `| field | type | description` line per field, so `sed -n '/^#### Foo$/,/^#### /p'` prints exactly one definition. ## 3. Is anything actually missing? - Newest released version: the first `#### ` block in `runtime/bot-api-update/api-changelog.md`, whose first line is `**Bot API X.Y**`. - Version the package supports: the line in `README.md` that reads `✔️ Telegram Bot API X.Y () is **fully supported**.` If they match, the work is already done: tell the user that the package is up to date with Bot API X.Y and **stop** — no branch, no plan, no commits. If the package is behind by more than one release, cover every missing release in this run, oldest first, in one plan. Otherwise create the branch, named like the previous ones (`api102` for 10.2, `api10` for 10.0, `api96` for 9.6 — `api` + the version digits without the dot): ```bash git switch -c api103 ``` ## 4. Write the plan Put the plan in `runtime/bot-api-update/plan.md` (gitignored — it is a working document, never committed). Split it as finely as it can reasonably be split. Rules for slicing: - One new type class = one item. One new method class = one item. - One new field on an existing type = one item; several new fields on the *same* type coming from the same changelog bullet may share one item. - One changelog bullet that adds the same parameter to a dozen methods = one item (it is one logical change and one `CHANGELOG.md` line). - A new interface plus its `ValueProcessor` and `ObjectFactory` registration = one item; each implementation of that interface is its own item. - Every item covers its own tests. Tests are never a separate trailing item. - Order items so dependencies come first (types before the methods that use them). Close the plan with these fixed items: 1. Update the supported-version line in `README.md`. 2. Add the `CHANGELOG.md` entries. 3. `composer cs-fix` + `composer rector` (step 7). 4. Verification (step 8). Item template: ```markdown ## Bot API 10.3 - [ ] 1. Add `EphemeralMessageParameters` type Changelog: Added the class EphemeralMessageParameters ... Files: src/Type/EphemeralMessageParameters.php, tests/Type/EphemeralMessageParametersTest.php Changelog entry: New: Add `EphemeralMessageParameters` type. ``` Cross-check the finished plan against the changelog bullets: every bullet of the target version must be traceable to at least one item, including "Supported ...", "Replaced ..." and "Renamed ..." bullets, which are easy to miss. The `CHANGELOG.md` entries reference a PR that does not exist yet: this skill never pushes the branch and never opens a pull request — the user does that themselves once the work is reviewed. Only the *number* is needed here, and it is the next free issue/PR number: ```bash gh issue list --state all --limit 1 --json number gh pr list --state all --limit 1 --json number ``` Take the larger number, add 1, and confirm that number with the user in step 5. ## 5. Agree the plan with the user Show the user the plan (summary plus the item list) and the PR number you intend to use, and ask for confirmation or corrections. Do not start implementing before they answer. Apply whatever they change to `runtime/bot-api-update/plan.md` first. ## 6. Implement, item by item For each item, in order: 1. Implement the source change following `AGENTS.md` (backward compatibility is preserved; new constructor parameters go last with a default). 2. Write or extend the tests in the same step. 3. Run the affected tests: `vendor/bin/phpunit --filter=`. 4. Commit only the files of this item: ```bash git add git commit -m "Add EphemeralMessageParameters type" ``` English, imperative, one line — the PR is squashed, so these are working notes. 5. Mark the item `[x]` in `runtime/bot-api-update/plan.md`. Never `git add -A` — `runtime/` is ignored, but stray files are not worth the risk. Never commit anything under `runtime/`. If an item turns out to be wrong or to need splitting, update `runtime/bot-api-update/plan.md` and tell the user what changed, then continue. ## 7. cs-fix and rector ```bash composer cs-fix composer rector composer test ``` Review the diff these tools produce before committing it — rector occasionally rewrites something in a way that conflicts with the project style. Commit as `Apply cs-fix and rector`. ## 8. Verification Report all four results to the user, honestly, with the actual output of anything that fails. 1. **Completeness.** Walk the changelog bullets of the target version one by one and confirm each is implemented in `src/`. Confirm every `[ ]` in `runtime/bot-api-update/plan.md` is now `[x]`. 2. **Tests.** ```bash composer test ``` 3. **Coverage — must be 100%.** ```bash XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text # or `composer coverage` for HTML ``` If PHPUnit warns `No code coverage driver available` (the usual case in this environment — neither Xdebug nor PCOV is installed), say so plainly instead of claiming coverage. Then fall back to a manual check: every class added or changed in this branch (`git diff --stat master...HEAD -- src`) has a corresponding test that exercises the new code, including every new facade method in `src/TelegramBotApi.php`. Tell the user that CI (Coveralls) gives the authoritative number. 4. **Static analysis — must be clean.** ```bash composer psalm composer dependency-analyser ``` Finish with a short summary: version ported, number of commits, what each verification step returned, and anything left open. Leave the branch local and unpushed — say that pushing it and opening the PR is up to the user.