Sopel 7: Planned rename of sopel.web -> sopel.tools.web

sopel_7.md

@@ -154,8 +154,7 @@ deprecated, leaving future versions free to move the callback storage if needed.
 ### Removal of `bot.privileges`
 
 Sopel 7.x will be the last release series to support the `bot.privileges` data
-structure (deprecated in [Sopel 6.2.0]({% link _changelogs/6.2.0.md %}),
-released January 16, 2016).
+structure (deprecated in [Sopel 6.2.0][v6.2.0], released January 16, 2016).
 
 Beginning in Sopel 8, `bot.privileges` will be removed and modules trying to
 access it will throw an exception. `bot.channels` will be the _only_ place to
@@ -170,3 +169,40 @@ version in their requirements.
 If you use third-party modules that have not been updated, we encourage you to
 inform the author(s) politely that they need to update. Or better yet, submit
 a pull request or patch yourself!
+
+### Rename/cleanup of `sopel.web`
+
+While the whole `sopel.web` module was marked as deprecated in [Sopel
+6.2.0][v6.2.0], because it largely serves as a wrapper around the `requests`
+library, parts of it seem to be useful enough that they should be kept around.
+
+For Sopel 8, we intend to move `sopel.web` to `sopel.tools.web`. Ideally the new
+location will be available in Sopel 7 to provide a transitional period. Similar
+to how importing from both `willie` and `sopel` worked in the run-up to Sopel
+6.0, it will be possible to do any of the following during Sopel 7's life cycle:
+
+  - `import sopel.web`
+  - `from sopel import web`
+  - `import sopel.tools.web`
+  - `from sopel.tools import web`
+
+In Sopel 8, we will remove the pointers from `sopel.web` to the new location.
+These explicitly deprecated functions will also be removed at the same time:
+
+  - `sopel.web.get()` — use `requests.get()` directly instead
+  - `sopel.web.head()` — use `requests.head()` directly instead
+  - `sopel.web.post()` — use `requests.post()` directly instead
+  - `sopel.web.get_urllib_object()` — seriously, just use [`requests`][requests]
+
+We will also tweak the module constants:
+
+  - `sopel.web.default_headers`: renamed to `sopel.tools.web.DEFAULT_HEADERS`
+  - `sopel.web.ca_certs`: removed in `sopel.tools.web` — it no longer has any
+    function (and was probably not useful for Sopel plugins to import, anyway)
+
+New additions to Sopel's web tools (there may be a few) will be available only
+in the new location (`sopel.tools.web`). Functions and constants that we plan to
+remove (as listed above) will be available only from the old `sopel.web` module.
+
+  [requests]: https://pypi.org/project/requests/
+  [v6.2.0]: {% link _changelogs/6.2.0.md %}