FEP-9967: Update proposal (#879)

- New "Summary".
- Require poll option text to be escaped before inclusion in HTML.
- Fixed validation rules in "Receiving a vote" section.
- Allowed debouncing when publishing poll results.
- Clarified what poll reset means.
- Added `voters` collection to "Future work" section.

Reviewed-on: https://codeberg.org/fediverse/fep/pulls/879

fep/9967/fep-9967.md

@@ -11,14 +11,14 @@ trackingIssue: https://codeberg.org/fediverse/fep/issues/478
 
 ## Summary
 
-How to make polls in [ActivityPub] network.
+This FEP documents how Mastodon and other [ActivityPub] applications implement polls.
 
 ## History
 
-Mastodon [implemented](https://github.com/mastodon/mastodon/pull/10111) polls in 2019 ([documentation][MastodonPolls]).
-
 ActivityStreams specification provides [recommendations](https://www.w3.org/TR/activitystreams-vocabulary/#questions) for representing questions, but these recommendations were found to be impractical and the de-facto standard differs from them.
 
+Mastodon [implemented](https://github.com/mastodon/mastodon/pull/10111) polls in 2019 ([documentation][MastodonPolls]).
+
 ## Requirements
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC-2119].
@@ -57,7 +57,7 @@ The value of this property MUST be an array of objects representing poll options
     - `type`: the `Collection` string.
     - `totalItems`: the total number of votes for this poll option.
 
-The `name` of a poll option MUST be unique within a poll. If the text contains [custom emoji][FEP-9098] microsyntax, the corresponding `Emoji` objects are added to the `tag` array of the `Question` object.
+The `name` of a poll option MUST be unique within a poll. If the text contains [custom emoji][FEP-9098] microsyntax, the corresponding `Emoji` objects are added to the `tag` array of the `Question` object. The text MUST be escaped before it is included in HTML.
 
 `Question` objects MAY have an `endTime` property indicating the time when the poll ends. Some implementations use `closed` property instead of `endTime` or in addition to it (even if the poll is open). Consumers MUST process `closed` in the same way as `endTime`.
 
@@ -150,7 +150,8 @@ Upon receving a vote, the author of the poll performs the following checks:
 - The voter has a permission to vote (if the poll is not public).
 - The poll is still active (if `endTime` is specified).
 - The vote with the specified `id` is not already registered.
-- The vote with the specified `name` is not already registered (if multiple choices are not allowed).
+- The vote from the specified actor is not already registered (if multiple choices are not allowed).
+- The vote with the specified `name` is not already registered (if multiple choices are allowed).
 
 If any of these checks fails, the vote MUST be ignored.
 
@@ -158,7 +159,7 @@ Otherwise, the author of the poll updates the vote count for the specified poll
 
 ### Publishing results
 
-When actor that published a poll receives a vote, it publishes an `Update` activity containing the `Question` object with updated results. This activity MUST be delivered to the audience of the poll and to every actor that voted in the poll.
+When the actor that published a poll receives a vote, it publishes an `Update` activity containing the `Question` object with updated results. This activity MUST be immediately delivered to the actor that sent the vote. It SHOULD also be delivered to the audience of the poll and to every actor that voted in the poll. [Debouncing](https://developer.mozilla.org/en-US/docs/Glossary/Debounce) MAY be applied.
 
 ### Closing a poll
 
@@ -166,10 +167,16 @@ A poll is considered to be closed once the date specified by the `endTime` prope
 
 ## Editing options
 
-The type of a poll (single choice / multiple choices) and its options might be changed at any time. In that case the author of the poll MUST reset the vote counts.
+The type of a poll (single choice / multiple choices) and its options might be changed at any time. In that case the author of the poll MUST reset it:
+
+- Empty the `replies` collection of every poll option.
+- Set the `votersCount` to `0` (if implemented).
+- Publish an `Update` activity.
 
 ## Future work
 
+In order to address poll voters correctly in `Update` activities, a collection of voters needs to be introduced. This collection could be attached to a `Question` object using the `voters` property.
+
 The method of identifying votes described in this document is not reliable because a reply can look exactly like a vote. Alternative representations are being discussed (e.g. the `Respond` activity).
 
 ## JSON schemas