Docs: add section to upgrade guide for p.restapi 8 (#1689)

* Docs: add section to upgrade guide for p.restapi 8 * Update docs/source/upgrade-guide.md Co-authored-by: David Glick <[email protected]> --------- Co-authored-by: David Glick <[email protected]>
plone · Aug 24, 2023 · d3ab72b · d3ab72b
1 parent 47a6402
commit d3ab72b
Showing 1 changed file with 13 additions and 29 deletions.
diff --git a/docs/source/upgrade-guide.md b/docs/source/upgrade-guide.md
@@ -12,6 +12,12 @@ myst:
 This upgrade guide lists all breaking changes in `plone.restapi`.
 It explains the steps that are needed to upgrade to the latest version.
 
+## Upgrading to `plone.restapi` 8.x
+
+plone.restapi 8.x dropped support for Python 2 and Plone 5.1 and 4.3.
+Upgrading to plone.restapi 8.x does not require any changes to your code base if you use Python 3 and Plone 5.2 or newer.
+
+If you use Python 2 and a Plone version older than 5.2, stick with plone.restapi 7.x.
 
 ## Upgrading to `plone.restapi` 7.x
 
@@ -20,7 +26,6 @@ Now its behavior is consistent regarding the `items` attribute.
 Now the `items` attribute is present, even if the element of the tree does not have child elements, in which case it will be an empty array.
 This might affect some logins via JavaScript, specifically if the condition is checking for the existence of the `items` attribute and expects it to be `undefined`.
 
-
 ## Upgrading to `plone.restapi` 6.x
 
 `plone.restapi` 6.0.0 removes the `IAPIRequest` marker interface (<https://github.com/plone/plone.restapi/pull/819>).
@@ -44,7 +49,6 @@ If you need to fix object IDs, you can do one of the following:
 We expect that most content actually will not be affected.
 See <https://github.com/plone/plone.restapi/issues/827> for more details.
 
-
 ## Upgrading to `plone.restapi` 5.x
 
 `plone.restapi` 5.0.0 introduces the following breaking change:
@@ -88,7 +92,6 @@ to:
 This change affects the `GET`, `PATCH`, and `POST` formats.
 It should only affect you if you use Volto.
 
-
 ## Upgrading to `plone.restapi` 4.x
 
 `plone.restapi` 4.0.0 introduces the following breaking changes:
@@ -98,7 +101,6 @@ It should only affect you if you use Volto.
 3.  Serialize widget parameters into a `widgetOptions` object instead of adding them to the top level of the schema property.
 4.  The vocabularies endpoint does no longer returns an `@id` for terms, the results are batched, and terms are now listed as `items` instead of `terms` to match other batched responses.
 
-
 ### Serialization and Deserialization of fields with vocabularies
 
 The serialization of fields with vocabularies, such as `Choice`, now return the `token` and the `title` of the vocabulary term instead of the stored value.
@@ -140,7 +142,6 @@ Deserialization accepts objects that contain a token, but also just the token or
 
 However, it is highly recommended to always use the token, as vocabulary terms may contain values that are not JSON serializable.
 
-
 ### Choice and List fields return link to vocabulary instead of the values
 
 Choice and List fields using named vocabularies are now serialized with a `vocabulary` property, giving the URL of the `@vocabularies` endpoint for the vocabulary instead of including `choices`,
@@ -177,7 +178,6 @@ New response:
 },
 ```
 
-
 ### Serialize widget parameters into a `widgetOptions` object
 
 Serialize widget parameters into a `widgetOptions` object instead of adding them to the top level of the schema property.
@@ -199,7 +199,6 @@ New response:
 }
 ```
 
-
 ### Example: Vocabularies Subjects Field
 
 The `subjects` field is now serialized as an `array` of `string` items using the `plone.app.vocabularies.Keywords` vocabulary.
@@ -233,7 +232,6 @@ New response:
 }
 ```
 
-
 ### Example: Available Time Zones Field (vocabulary in `items`)
 
 Old response:
@@ -289,7 +287,6 @@ New response:
 },
 ```
 
-
 ### Example: Weekday Field (vocabulary in main property)
 
 Old response:
@@ -363,7 +360,6 @@ New response:
 },
 ```
 
-
 ### Vocabularies Endpoint
 
 The vocabularies endpoint no longer returns an `@id` for terms.
@@ -394,20 +390,18 @@ New response:
 {
   "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes",
   "items": [
-      {
-        "title": "Collection",
-        "token": "Collection"
-      },
-      "…"
+    {
+      "title": "Collection",
+      "token": "Collection"
+    },
+    "…"
   ],
   "items_total": 12
 }
 ```
 
-
 ## Upgrading to `plone.restapi` 3.x
 
-
 ### Image scales
 
 Image download URLs and image scale URLs are created using the UID-based URL formats.
@@ -449,7 +443,6 @@ New Response:
 }
 ```
 
-
 ### `@sharing` endpoint
 
 The `available_roles` property in the response to a `GET` request to the `@sharing` endpoint has changed.
@@ -507,7 +500,6 @@ Content-Type: application/json
 }
 ```
 
-
 ### Custom Content Deserializers
 
 If you have implemented custom content deserializers, you have to handle the new `create` keyword in the `__call__` method, which determines if deserialization is performed during object creation or while updating an object.
@@ -516,13 +508,11 @@ Deserializers should only fire an `IObjectModifiedEvent` event if an object has
 
 See [Dexterity content deserializer](https://github.com/plone/plone.restapi/blob/master/src/plone/restapi/deserializer/dxcontent.py) for an example.
 
-
 ## Upgrading to `plone.restapi` 2.x
 
 `plone.restapi` 2.0.0 converts all datetime, DateTime and time objects to UTC before serializing.
 The translations endpoint becomes "expandable", which introduces the following breaking changes.
 
-
 ### Translations
 
 Previously when using the `@translations` endpoint in `plone.restapi` 1.x, the endpoint returned a `language` key with the content object's language and a `translations` key with all its translations.
@@ -567,7 +557,6 @@ Content-Type: application/json
 }
 ```
 
-
 ## Upgrading to `plone.restapi` 1.0b1
 
 In `plone.restapi` 1.0b1 the `url` attribute on the {ref}`navigation` and {ref}`breadcrumbs` endpoint was renamed to `@id` to be consistent with other links/URLs used in `plone.restapi`.
@@ -720,7 +709,6 @@ Pull Request:
 
 - <https://github.com/plone/plone.restapi/pull/459>
 
-
 ## Upgrading to `plone.restapi` 1.0a25
 
 `plone.restapi` 1.0a25 introduced three breaking changes:
@@ -729,8 +717,7 @@ Pull Request:
   Use top level `@navigation` and `@breadcrumb` endpoints instead. [timo]
 - Remove `sharing` attributes from `GET` response. [timo, jaroel]
 - Convert `richtext` using `.output_relative_to`.
-  Direct conversion from `RichText` is no longer supported as we *always* need a context for the `ITransformer`. [jaroel]
-
+  Direct conversion from `RichText` is no longer supported as we _always_ need a context for the `ITransformer`. [jaroel]
 
 ### Remove @components endpoint
 
@@ -769,7 +756,6 @@ Pull Request:
 
 - <https://github.com/plone/plone.restapi/pull/425>
 
-
 ### Remove `sharing` attribute
 
 The `sharing` attribute was removed from all content `GET` responses:
@@ -791,21 +777,19 @@ Pull Request:
 
 - <https://github.com/plone/plone.restapi/commit/1b5e9e3a74df22e53b674849e27fa4b39b792b8c>
 
-
 ### Convert `richtext` using `.output_relative_to`
 
 Use `.output_relative_to` to convert `richtext`.
 
 Changelog:
 
 - Convert `richtext` using `.output_relative_to.`
-  Direct conversion from `RichText` is no longer supported as we *always* need a context for the `ITransformer`. [jaroel]
+  Direct conversion from `RichText` is no longer supported as we _always_ need a context for the `ITransformer`. [jaroel]
 
 Pull Request:
 
 - <https://github.com/plone/plone.restapi/pull/428>
 
-
 ## Upgrading to `plone.restapi` 1.0a17
 
 `plone.restapi` 1.0a17 changed the serialization of the `richtext` "text" field for content objects from using `raw` (a Unicode string with the original input markup):