Complement updates with promotions

[jace]

The Update model is meant for posting updates within a project as new information becomes available – such as a Zoom meeting link or a YouTube video.

However, updates are also frequently used to promote newer projects. This usage is spammy as multiple past projects get the same update content. We need a distinct variant of updates to make this work properly.

1. Instead of posting multiple updates in a past project, post a single update in the new project.
2. Mark this update as a promotion, and select the past projects it should be promoted in.
3. This update will now appear in the notifications for past project participants, but as it is a single update, it will only appear once, without spamming.
4. It will (should?) not appear in the new project's updates.

This feature can be implemented using either a new Promotion data model, or by reusing the existing Update model and adding a flag. The flag-based approach will make implementation and maintenance simpler.

There is a pending problem with authorization: editors can write updates and edit all updates within the same project, but to promote to another project's participants, they will need authorization from an editor there. While one user may be an editor in both places, another editor may not be, so there has to be an explicit authorization token linked to the editor who authorized. This will need a "promotion authorization" model with both "requested" and "granted" flags and corresponding UI.

[jace]

As clarified in #1015, promotion authorization requires the promoter role (formerly concierge), not editor. This will mean that updates can now be written by both editors and promoters.

[jace]

If the Update model is to be reused for promotions, it will need a distinguishing flag and a support model.

1. UPDATE_STATE currently has DRAFT, PUBLISHED and DELETED. It could use an additional PROMOTED state to indicate it's published as a promotion. However, a deleted promotion will have no indication of what it was, and a draft can't indicate what it is meant to be. Also, an update can't simultaneously appear in this and other projects. We may instead need a distinct is_promotion flag. Hasjob has a similar problem where the rarely-used "announcement" feature is a state on job posts instead of a flag. It is space-efficient as a state, but it makes the publishing workflow trickier as it needs to ride on top of the verify+publish workflow with an additional state change. A flag will allow cleaner workflow.

2. A new UpdatePromotion support model should link an update with other projects. It will need these columns:

   • update_id and project_id as the join columns
   • requested_by and requested_at (non-nullable)
   • granted_by and granted_at
   • revoked_by and revoked_at
   • is_active column property (defined as granted_at is not None and revoked_at is None)
   • Note: the existence of an UpdatePromotion cannot be used to determine if an update is a promotion as it is an inefficient query

3. A PromotedUpdateNotification to show updates to participants in these projects.

   • Document: Update (or document is Update.project and fragment is Update to prevent dupe notifications when the update is re-promoted)
   • Role: promoted_participant acquired from Update -> UpdatePromotion -> Project
   • Note: UpdatePromotion cannot be the document/fragment of the notification as it will result in duplicated notifications per targeted project

[jace]

The existing VISIBILITY_STATE enum is a better candidate for marking a promotion than having a separate promotion flag. It has an existing PUBLIC and RESTRICTED and can get an additional PROMOTION (not PROMOTED as that is the term for this update in the target project, not its natural state).

Edit (17 Feb): RESTRICTED and PROMOTION don't work. It has to be PROMOTED. "Promotion" is a separate model anyway.

[jace]

Updates get an update number when they are published. However, promotions cannot have an update number as they do not appear in sequence in their owning project. This presents a problem. Options:

1. Keep update numbers for promotions and sacrifice sequence (affecting reader's perception), or
2. Don't assign numbers, and don't allow change from promotion to regular update and vice versa, or
3. Assign and revoke numbers as necessary:
   1. When publishing, assign a number only if this is not a promotion.
   2. When converting from regular to promotion, revoke the number (at risk that the number will be reused by the next regular update).
   3. When converting from promotion to regular, re-assign a number.

[jace]

The first_published flag (returned by Update.publish()) is also a problem. It is currently used to determine whether a notification should be sent, and with promotions added, it will also be used to determine which notification is sent.

Once an update is published, changing its type from regular to promotion will be meaningless as it won't notify the targets. Therefore this change should not be allowed past first publication (ie, when published_at is None, not when state is DRAFT).

[jace]

The conditional states UNPUBLISHED and WITHDRAWN specifically track these variants of DRAFT. UNPUBLISHED can be a requirement for the make_promotion and make_regular transitions.

[jace]

Okay, so decision is that an update can be toggled between regular (public, restricted) and promotion while it is unpublished. It can't be changed after publication (or withdrawal). This removes the first_published concern too.

[jace]

An example of cross-promotion workflow:

Users: u1, u2, u3, u4
Projects: p1, p2, p3, p4

Project-Promoter relationships:

p1: u1, u2, u3
p2: u1, u2
p3: u3
p4: u4

Scenario:

1. u1 wants to promote p1. There are two ways:
   1. In p1, u1 taps on the "promote this project" button and is asked to write a draft message. u1 is informed that this message will be shown in other projects and must be written from their perspective. For example, "since you have participated here, you may be interested in something else".
   2. u1 goes to the older project p2, where u1 is also a promoter, and taps the "promote a new project" button. u1 is then asked to select the other project, and selects p1.
2. u1 writes a draft message. It is saved in p1 as a promotion (regardless of entry point being p1 or p2 in step 1), as it is p1 being promoted.
3. u1 is asked to select other projects to promote in. If u1 arrived via step 1.i, p2 is available to select. If they arrived via step 1.ii, p2 is already selected. There are no other project available to u1.
4. u1 asks fellow promoters u2 and u3 to promote. This conversation happens outside the application.
5. u2 and u3 receive the draft link from u1 (outside the app), or they go to p1's updates and find it in the list of drafts.
6. When u2 opens the list of projects to promote in, p2 is already present. No other project is available to add. u2 can remove p2 as they are a promoter of p2.
7. When u3 opens then the list, p2 is already present but cannot be removed, as they are not a promoter of p2. However, they can add p3.
8. u4 cannot do anything as they are not a promoter of p1.
9. p4 is not available to add as there is no shared promoter.
10. Any of u1, u2 and u3 can publish the promotion.

A future version of this feature will support cross-promotion when there are no common promoters, but this is not a current requirement.

[jace]

This issue has a partial implementation in #1038, but it has been abandoned for two years as our priorities shifted. We are now moving away from Projects as the locus of user presence towards account (nee profile) followers, so we need new ideas based around accounts.