From bb0d31300379597380909078fcf2197bc83739a0 Mon Sep 17 00:00:00 2001 From: Waffle Date: Thu, 8 Jul 2021 02:21:12 +0300 Subject: [PATCH] Add migration guide --- MIGRATION_GUIDE.md | 162 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 MIGRATION_GUIDE.md diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md new file mode 100644 index 00000000..d945a6e6 --- /dev/null +++ b/MIGRATION_GUIDE.md @@ -0,0 +1,162 @@ +This document describes breaking changes of `teloxide` crate, as well as the ways to update code. +Note that the list of required changes is not fully exhaustive and it may lack something in rare cases. + +## 0.4 -> 0.5 + +### core + +#### Field type changes + +Types of some fields were changed to be more accurate. +If you used them, you may need to change types in your code too. + +Example: +```diff +let ps: PhotoSize = /* ... */; +-let w: i32 = ps.width; ++let w: u32 = ps.width; +``` + +List of changed types: +- `PhotoSoze::width`: `i32` -> `u32` +- `PhotoSoze::height`: `i32` -> `u32` +- `Restricted::until_date`: `i32` -> `DateTime` +- `Kicked::until_date` (`Banned::until_date`): `i32` -> `DateTime` +- `PublicChatSupergroup::slow_mode_delay`: `Option` -> `Option` +- `User::id`: `i32` -> `i64` (note: all methods which are accepting `user_id` were changed too) + + +#### Method output types + +In teloxide `v0.4` (core `v0.2`) some API methods had wrong return types. +This made them practically unusable as they've always returned parsing error. +On the offchance you were using the methods, you may need to adjust types in your code. + +List of changed return types: +- `get_chat_administrators`: `ChatMember` -> `Vec` +- `send_chat_action`: `Message` -> `True` +- `leave_chat`: `String` -> `True` +- `pin_chat_message`: `String` -> `True` +- `set_chat_description`: `String` -> `True` +- `set_chat_photo`: `String` -> `True` +- `set_chat_title`: `String` -> `True` +- `unpin_all_chat_messages`: `String` -> `True` +- `unpin_chat_message`: `String` -> `True` + + +#### Method parameter types + +Some API methods accept different types now. +If you've used changed parameters, you need to adjust code for new types. + +Examples: +```diff +let bot = Bot::new("TOKEN").auto_send(); + +-bot.set_webhook("url").await?; ++bot.set_webhook(Url::parse("url").unwrap()).await?; + +let link = bot + .create_chat_invite_link(chat_id) +- .expire_date(timestamp) +# Note: this is not the only way to create `DateTime`. Refer to `chrono` docs for more. ++ .expire_date(DateTime::::from_utc( ++ NaiveDateTime::from_timestamp(timestamp, 0), Utc) ++ ) + .await?; +``` + +See also: [teloxide examples fixes](https://github.com/teloxide/teloxide/pull/408/files/369e43aa7ed1b192d326e6bdfe76f3560001353f..18f88cc034e97fd437c48930728c1d5d2da7a14d). + +List of changed required params: +- `SetWebhook::url`: `String` -> `Url` + +List of changed optional params: +- `AnswerCallbackQuery::url`: `String` -> `Url` +- `SendInvoice::photo_url`: `String` -> `Url` +- `CreateChatInviteLink::expire_date`: `i64` -> `DateTime` +- `EditChatInviteLink::expire_date`: `i64` -> `DateTime` +- `KickChatMember::until_date`: `u64` -> `DateTime` +- `RestrictChatMember::until_date`: `u64` -> `DateTime` +- `SendPoll::close_date`: `u64` -> `DateTime` + + +#### Renamed items + +Some items (fields, variants, types, methods) were renamed. +If you used them, you should start using new names. + +Example: +```diff +-bot.send_chat_action(chat, ChatAction::RecordAudio).await?; ++bot.send_chat_action(chat, ChatAction::RecordVoice).await?; + +-if chat_member.is_kicked() { ++if chat_member.is_banned() { + /* ... */ +} +``` + +List of renamed items: +- `ChatAction::RecordAudio` -> `RecordVoice` +- `ChatAction::UploadAudio` -> `UploadVoice` +- `ChatMemberKind::Creator` -> `Owner` +- `ChatMemberKind::Kicked` -> `Banned` +- `Creator` -> `Owner` +- `Kicked` -> `Banned` +- `ChatMemberKind::is_Creator` -> `is_owner` * +- `ChatMemberKind::is_kicked` -> `is_banned` * +- `ChatMemberStatus::Creator` -> `Owner` +- `ChatMemberStatus::Kicked` -> `Banned` +- `kick_chat_member` -> `ban_chat_member` * +- `get_chat_members_count` -> `get_chat_member_count` * + +\* Old methods are still accessible, but deprecated + + +#### Added `impl Clone` for {`CacheMe`, `DefaultParseMode`, `Throttle`} + +Previously said bot adaptors were lacking `Clone` implementation. +To workaround this issue it was proposed to wrap bot in `Arc`. +Now it's not required, so you can remove the `Arc`: + +```diff +let bot = Bot::new(token).parse_mode(ParseMode::MarkdownV2); +-let bot = Arc::new(bot); +``` + + +### teloxide + +#### Mutable reference for dispatching + +`Dispatcher::dispatch` and `Dispatcher::dispatch_with_listener` now require mutable (unique) reference to self. +If you've used variable to store `Dispatcher`, you need to make it mutable: + +```diff +-let dp = Dispatcher::new(); ++let mut dp = Dispatcher::new(); +/* ... */ +dp.dispatch(); +``` + + +#### Listener refactor + +`UpdateListener` trait was refactored. +If you've used `polling`/`polling_default` provided by teloxide, no changes are required. +If, however, you've used or implemented `UpdateListener` directly or used a `Stream` as a listener, +then you need to refactor your code too. + +See also: [teloxide examples fixes](https://github.com/teloxide/teloxide/pull/385/files/8785b8263cb4caebf212e2a66a19f73e653eb060..c378d6ef4e524da96718beec6f989e8ac51d1531). + + +#### `polling_default` + +`polling_default` is now async, but removes webhook. + +Example fix: +```diff +-let listener = polling_default(bot); ++let listener = polling_default(bot).await; +```