nocebo/diaspora_federation
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update documentation for the future of reshares

Browse source 
See #83
This commit is contained in:
Benjamin Neff 2017-09-12 01:31:40 +02:00
parent 30859e54b4
commit 23fcf11acb
No known key found for this signature in database
GPG key ID: 971464C3F1A90194
4 changed files with 26 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/_entities/comment.md
View file

@ -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]

2
docs/_entities/like.md
View file

@ -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]

9
docs/_entities/post.md
View file

@ -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

29
docs/_entities/reshare.md
View file

@ -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>
~~~