Deprecate on_threepid_bind

docs/modules/third_party_rules_callbacks.md

@@ -251,6 +251,13 @@ If multiple modules implement this callback, Synapse runs them all in order.
 
 _First introduced in Synapse v1.56.0_
 
+**<span style="color:red">
+This callback is deprecated in favour of the `on_add_user_third_party_identifier` callback, which
+features nearly the same functionality. The only difference is that while `on_threepid_bind`
+was called *after* a third-party ID was associated with a user's account on the homeserver,
+`on_add_user_third_party_identifier` is called just *before* a third-party ID is associated.
+</span>**
+
 ```python
 async def on_threepid_bind(user_id: str, medium: str, address: str) -> None:
 ```

docs/upgrade.md

@@ -99,10 +99,10 @@ in a future release.
 
 ## The `on_threepid_bind` module callback method has been deprecated
 
-The [`on_threepid_bind`](modules/third_party_rules_callbacks.md#on_threepid_bind) "third-party rules"
+The [`on_threepid_bind`](modules/third_party_rules_callbacks.md#onthreepidbind) "third-party rules"
 Synapse module callback method has been deprecated
 in favour of a new module method,
-[`on_add_user_third_party_identifier`](modules/third_party_rules_callbacks.md#on_add_user_third_party_identifier).
+[`on_add_user_third_party_identifier`](modules/third_party_rules_callbacks.md#onadduserthirdpartyidentifier).
 `on_threepid_bind` will be removed in a future version of Synapse. You should check whether any Synapse
 modules in use in your deployment are making use of `on_threepid_bind`, and update them where possible.
 
@@ -119,7 +119,7 @@ do so via an [identity server](https://spec.matrix.org/latest/identity-service-a
 it was only called when a user added a third-party identifier on the local homeserver.
 
 Module developers may also be interested in the related
-[`on_remove_user_third_party_identifier`](modules/third_party_rules_callbacks.md#on_remove_user_third_party_identifier)
+[`on_remove_user_third_party_identifier`](modules/third_party_rules_callbacks.md#onremoveuserthirdpartyidentifier)
 module callback method that was also added in Synapse v1.77.0. This new method is called when a
 user removes a third-party identifier from their account.
 

synapse/events/third_party_rules.py

@@ -530,6 +530,9 @@ async def on_threepid_bind(self, user_id: str, medium: str, address: str) -> Non
         local homeserver, not when it's created on an identity server (and then kept track
         of so that it can be unbound on the same IS later on).
 
+        THIS MODULE CALLBACK METHOD HAS BEEN DEPRECATED. Please use the
+        `on_add_user_third_party_identifier` callback method instead.
+
         Args:
             user_id: the user being associated with the threepid.
             medium: the threepid's medium.