From 23fcf11acbef7339c36e7bed959ff155c58d775f Mon Sep 17 00:00:00 2001
From: Benjamin Neff <benjamin@coding4coffee.ch>
Date: Tue, 12 Sep 2017 01:31:40 +0200
Subject: [PATCH] Update documentation for the future of reshares

See #83
---
 docs/_entities/comment.md |  3 ++-
 docs/_entities/like.md    |  2 +-
 docs/_entities/post.md    |  9 ++++++++-
 docs/_entities/reshare.md | 29 +++++++++++++++--------------
 4 files changed, 26 insertions(+), 17 deletions(-)

diff --git a/docs/_entities/comment.md b/docs/_entities/comment.md
index 7b8851a..27e8891 100644
--- a/docs/_entities/comment.md
+++ b/docs/_entities/comment.md
@@ -2,7 +2,8 @@
 title: Comment
 ---
 
-This entity represents a comment to some kind of [Post][post] ([StatusMessage][status_message] or [Reshare][reshare]).
+This entity represents a comment to some kind of [Post][post] ([StatusMessage][status_message]
+or currently still a [Reshare][reshare]).
 
 See also: [Relayable][relayable]
 
diff --git a/docs/_entities/like.md b/docs/_entities/like.md
index fcc635d..5772267 100644
--- a/docs/_entities/like.md
+++ b/docs/_entities/like.md
@@ -6,7 +6,7 @@ This entity represents a like to some kind of post (e.g. status message).
 
 The `parent_type` can be one of:
 
-* [Post][post] ([StatusMessage][status_message] or [Reshare][reshare])
+* [Post][post] ([StatusMessage][status_message] or currently still a [Reshare][reshare])
 * [Comment][comment] (diaspora\* doesn't support this at the moment)
 
 See also: [Relayable][relayable]
diff --git a/docs/_entities/post.md b/docs/_entities/post.md
index 961b751..1c113ea 100644
--- a/docs/_entities/post.md
+++ b/docs/_entities/post.md
@@ -2,7 +2,14 @@
 title: Post
 ---
 
-This is the abstract parent type of [StatusMessage][status_message] and [Reshare][reshare].
+This is the abstract parent type of [StatusMessage][status_message] and currently still [Reshare][reshare].
+
+{% include warning_box.html
+   title="Future of reshares"
+   content="<p>Reshare will not inherit from Post in the future anymore! More information about this
+   can be found <a href=\"/diaspora_federation/entities/reshare.html\">here</a> or
+   in <a href=\"https://github.com/diaspora/diaspora_federation/issues/83\">this issue</a>.</p>"
+%}
 
 ## Common Properties
 
diff --git a/docs/_entities/reshare.md b/docs/_entities/reshare.md
index dc08931..e6f15df 100644
--- a/docs/_entities/reshare.md
+++ b/docs/_entities/reshare.md
@@ -2,15 +2,25 @@
 title: Reshare
 ---
 
-This entity represents a reshare of a [StatusMessage][status_message]. It inherits from [Post][post].
+This entity represents a reshare of a [StatusMessage][status_message].
+
+{% include warning_box.html
+   title="Future of reshares"
+   content="<p>Current versions of diaspora* handle reshares like they inherit from
+   <a href=\"/diaspora_federation/entities/post.html\">Post</a> and allow interactions (Comments and
+   Likes) on the reshare. In the future, the reshare entity will only be used to increase the spread of a
+   Post, more information about this can be found in
+   <a href=\"https://github.com/diaspora/diaspora_federation/issues/83\">this issue</a>.</p>
+   <p>There currently exists a special case for reshares with a deleted root post. It is valid when the
+   reshare doesn't include <code>root_author</code> and <code>root_guid</code>. If only one of
+   <code>root_author</code> and <code>root_guid</code> is present, the entity is not valid. Once
+   reshares are only used to increase the reach of a post, reshares without <code>root_author</code> and
+   <code>root_guid</code> will no longer be valid and reshares will be deleted if the original post is deleted.</p>"
+%}
 
 The recipient must [fetch][fetching] the root from `root_author` if the post is not already known.
 When the `root_guid` is already available locally, the recipient must validate that it's from `root_author`.
 
-A special case when the entity doesn't include `root_author` and `root_guid` is allowed. This case represents
-a reshare for a deleted post. If there is only one of `root_author` and `root_guid` is present, then the entity
-is not valid.
-
 ## Properties
 
 | Property      | Type                         | Description                                                   |
@@ -21,13 +31,6 @@ is not valid.
 | `root_author` | [diaspora\* ID][diaspora-id] | The diaspora\* ID of the author of the reshared [Post][post]. |
 | `root_guid`   | [GUID][guid]                 | The GUID of the reshared [Post][post].                        |
 
-## Optional Properties
-
-| Property                | Type (Length)          | Description                                                                                |
-| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------ |
-| `provider_display_name` | [String][string] (255) | The means by which the author has posted the reshare.                                      |
-| `public`                | [Boolean][boolean]     | `false` if the reshare is not public (diaspora\* currenlty only supports public reshares). |
-
 ## Example
 
 ~~~xml
@@ -35,10 +38,8 @@ is not valid.
   <author>alice@example.org</author>
   <guid>a0b53e5029f6013487753131731751e9</guid>
   <created_at>2016-07-12T00:36:42Z</created_at>
-  <provider_display_name/>
   <root_author>bob@example.com</root_author>
   <root_guid>a0b53bc029f6013487753131731751e9</root_guid>
-  <public>true</public>
 </reshare>
 ~~~