From c77f771e2bed176acd6aa5011be006c800181809 Mon Sep 17 00:00:00 2001
From: Jonas L <jooola@users.noreply.github.com>
Date: Wed, 3 Jul 2024 11:14:17 +0200
Subject: [PATCH] docs: add v2 upgrade notes (#405)

Add upgrade notes for the new v2 release.
---
 README.md         |  6 ++--
 docs/index.md     |  1 +
 docs/upgrading.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 3 deletions(-)
 create mode 100644 docs/upgrading.md

diff --git a/README.md b/README.md
index e4c66181..4fe0b73f 100644
--- a/README.md
+++ b/README.md
@@ -45,9 +45,9 @@ for server in servers:
     print(f"{server.id=} {server.name=} {server.status=}")
 ```
 
-For more details, please see the [API reference](https://hcloud-python.readthedocs.io/en/stable/api.html).
-
-You can find some more examples under the [`examples/`](https://github.com/hetznercloud/hcloud-python/tree/main/examples) directory.
+- To upgrade the package, please read the [instructions available in the documentation](https://hcloud-python.readthedocs.io/en/stable/upgrading.html).
+- For more details on the API, please see the [API reference](https://hcloud-python.readthedocs.io/en/stable/api.html).
+- You can find some more examples under the [`examples/`](https://github.com/hetznercloud/hcloud-python/tree/main/examples) directory.
 
 ## Supported Python versions
 
diff --git a/docs/index.md b/docs/index.md
index 915e125c..32c1f094 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,6 +7,7 @@ installation.rst
 api.rst
 Hetzner Cloud API Documentation <https://docs.hetzner.cloud>
 contributing.rst
+upgrading.md
 changelog.md
 
 :::
diff --git a/docs/upgrading.md b/docs/upgrading.md
new file mode 100644
index 00000000..dd0c8ce2
--- /dev/null
+++ b/docs/upgrading.md
@@ -0,0 +1,78 @@
+# Upgrading
+
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Before upgrading, make sure to resolve any deprecation warnings.
+
+## Upgrading to v2
+
+- [#397](https://github.com/hetznercloud/hcloud-python/pull/397): The package version was moved from `hcloud.__version__.VERSION` to `hcloud.__version__`, make sure to update your import paths:
+
+```diff
+-from hcloud.__version__ import VERSION
++from hcloud import __version__ as VERSION
+```
+
+- [#401](https://github.com/hetznercloud/hcloud-python/pull/401): The deprecated `hcloud.hcloud` module was removed, make sure to update your import paths:
+
+```diff
+-from hcloud.hcloud import Client
++from hcloud import Client
+```
+
+- [#398](https://github.com/hetznercloud/hcloud-python/pull/398): The [`Client.poll_interval`](#hcloud.Client) property is now private, make sure to configure it while creating the [`Client`](#hcloud.Client):
+
+```diff
+-client = Client(token=token)
+-client.poll_interval = 2
++client = Client(
++   token=token,
++   poll_interval=2,
++)
+```
+
+- [#400](https://github.com/hetznercloud/hcloud-python/pull/400): The [`Client.request`](#hcloud.Client.request) method now returns an empty dict instead of an empty string when the API response is empty:
+
+```diff
+ response = client.request(method="DELETE", url="/primary_ips/123456")
+-assert response == ""
++assert response == {}
+```
+
+- [#402](https://github.com/hetznercloud/hcloud-python/pull/402): In the [`Client.isos.get_list`](#hcloud.isos.client.IsosClient.get_list) and [`Client.isos.get_all`](#hcloud.isos.client.IsosClient.get_all) methods, the deprecated `include_wildcard_architecture` argument was removed, make sure to use the `include_architecture_wildcard` argument instead:
+
+```diff
+ client.isos.get_all(
+-   include_wildcard_architecture=True,
++   include_architecture_wildcard=True,
+ )
+```
+
+- [#363](https://github.com/hetznercloud/hcloud-python/pull/363): In the [`Client.primary_ips.create`](#hcloud.primary_ips.client.PrimaryIPsClient.create) method, the `datacenter` argument was moved after `name` argument and is now optional:
+
+```diff
+ client.primary_ips.create(
+    "ipv4",
+-   None,
+    "my-ip",
+    assignee_id=12345,
+ )
+```
+
+```diff
+ client.primary_ips.create(
+    "ipv4",
+-   Datacenter(name="fsn1-dc14"),
+    "my-ip",
++   datacenter=Datacenter(name="fsn1-dc14"),
+ )
+```
+
+- [#406](https://github.com/hetznercloud/hcloud-python/pull/406): In the [`Client.servers.rebuild`](#hcloud.servers.client.ServersClient.rebuild) method, the single action return value was deprecated and is now removed. The method now returns a full response wrapping the action and an optional root password:
+
+```diff
+-action = client.servers.rebuild(server, image)
++resp = client.servers.rebuild(server, image)
++action = resp.action
++root_password = resp.root_password
+```