Update content in Starlight site version

src/content/docs/info.mdx → src/content/docs/about.mdx

@@ -1,5 +1,5 @@
 ---
-title: Project information
+title: Project overview
 description: An introduction to the Open Podcast API project
 sidebar:
    order: 1
@@ -9,11 +9,13 @@ The Open Podcast API project is inspired by and builds upon the [gPodder API](ht
 
 The initial discussions on GitHub led to a meeting in October 2022 with contributors from [AntennaPod](https://github.com/AntennaPod/AntennaPod/), [Funkwhale](https://dev.funkwhale.audio/), [Kasts](https://invent.kde.org/multimedia/kasts), [Podfriend](https://github.com/MartinMouritzen/Podfriend) and the [gPodder app for Nextcloud](https://github.com/thrillfall/nextcloud-gpodder).[^initialAPIdiscussions] A few months later, the first of the recurring meetings took place to start developing the specification.
 
-## Code of conduct
+## Join us!
 
-The Open Podcast API project abides by the Funkwhale code of conduct. Please familiarize yourself with it before participating in any of our community spaces.
+We encourage you to engage in the discussions, and provide feedback based on your implementation. [Check our homepage](/) how you can get involved.
 
-<LinkCard title="Code of conduct" description="Read the code of conduct on Funkwhale's website" href="https://funkwhale.audio/en_US/code-of-conduct"/>
+## Code of Conduct
+
+The Open Podcast API project abides by the [Funkwhale Code of Conduct](https://funkwhale.audio/en_US/code-of-conduct). Please familiarize yourself with it before participating in any of our community spaces.
 
 [^gPoddermaintainer]: [Call on the gPodder.net repository for a new maintainer](https://github.com/gpodder/mygpo/blob/81e3d13e00e6c3d6db7ee6a22734041bf6fde128/maintainer-needed.md)
 [^APforumGpodderIssues]: [Questions about gPodder.net issues on the AntennaPod forum](https://forum.antennapod.org/t/problem-with-gpodder-net/374)

src/content/docs/specs/index.mdx

@@ -8,9 +8,26 @@ sidebar:
    order: 1
 ---
 
+:::caution[Important]
+All specifications are currently 'in progress'. Breaking changes can occur as we implement specifications and address issues.
+:::
+
+Below you can find the specifications which are already available. We encourage all interested projects offering podcast listening and/or synchronization functionality to adopt and implement defined specifications. We also welcome feedback on these sepcifications.
+
+## Core and optional functionality
+
+To ensure that the end-user experience is consistent across implemenetations, the specifications mark endpoints and features as **Core** (required) and **Optional**.
+
+**Core**
+: The feature or endpoint must be supported by all clients and servers.
+
+**Optional**
+: The feature or endpoint is considered to be additional functionality. Clients and servers may optionally support any combination of these features. Any project implementing **Optional** functionality should inform users about what is supported.
+
+Which features a server supports will be exposed through a Capabilities endpoint.
+
 ## Core endpoints
 
 <CardGrid>
-   <LinkCard title="Versioning" description="Specs relating to API versioning" href="/specs/versioning" />
    <LinkCard title="Subscriptions" description="Specs relating to managing subscriptions" href="/specs/subscriptions" />
 </CardGrid>

src/content/docs/specs/subscriptions/index.mdx

@@ -27,4 +27,10 @@ Subscriptions represent the feeds a user has subscribed to. A subscription objec
 | `new_guid`             | String\<UUID\> | Yes       | The new GUID associated with the podcast                                                                                                                            |
 | `deleted`              | Datetime       | Yes       | The date on which data associated with the subscription was deleted by the user. This field is used to determine whether a `410 (Gone)` response should be returned |
 
+:::note[Tombstoning]
+Servers **should** hold all previous `guid` and `feed_url` field data with a link to the succeeding data (such that a path of values can be followed) or with a link to the most recent data. This enables the server to handle situations in which clients submit old data. For example:
+* A user finds a podcast, whose URL had changed, and adds the old URL in the app. Because the client doesn't have the old URL in its database, it recognizes the podcast as **new** and POSTs the `feed_url` to the `/subscriptions` endpoint. If the user is already subscribed to the podcast (with the current feed URL) this would lead to a duplicate subscription.
+* A user has a device that they didn't use for a very long time. In that time, a podcaster added a GUID in their feed, leading to updated data in this field. When the client connects to the server again to pull all episode changes since the last connection, it retrieves episodes with their current subscription `guid`. The client won't recognize the subscription and fail to update the status of episodes.
+:::
+
 [ISO 8601 format]: https://www.iso.org/iso-8601-date-and-time-format.html

src/content/docs/specs/subscriptions/update.mdx

@@ -25,7 +25,7 @@ This endpoint returns the following information:
 | ---------------------- | -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `new_feed_url`         | String         | No        | The URL of the podcast RSS feed. Only returned if the `feed_url` field was updated by the request                                                                   |
 | `is_subscribed`        | Boolean        | No        | Whether the user is subscribed to the podcast or not. Only returned if the `is_subscribed` field was updated by the request                                         |
-| `subscription_changed` | Datetime       | No        | The date on which the `is_subscribed` field was last updated. Presented in [ISO 8601 format]. Only returned if the `is_subscribed` field was updated by the request |
+| `subscription_changed` | Datetime       | No        | The date on which the `is_subscribed`or `feed_url` field was last updated. Presented in [ISO 8601 format]. Only returned if the `is_subscribed` field was updated by the request |
 | `guid_changed`         | Datetime       | No        | The date on which the podcast's GUID was last updated. Presented in [ISO 8601 format]. Only returned if the `guid` field was updated by the request                 |
 | `new_guid`             | String\<UUID\> | No        | The new GUID associated with the podcast. Only returned if the `guid` field was updated by the request                                                              |