Draft pages and publishing

Goals

1. Allow users to contribute content in a safe environment where it can be reviewed by moderators before it is published back.
2. Allow moderators to discover and manage user contributions by providing tools to review them, accept or reject individual contributions, and publish the final result.
3. Enable moderators to change published content without having to go through draft-process.
4. Edits to a page are reflected immediately as before while edits to a draft are not visible until it's published.

Non-Goals

These are the use cases we will purposely not be solving in this iteration of draft pages.

1. Drafts will only be for public deployments - deployments utilizing granular permissions to grant access to content will not be able to take advantage of drafts without making drafts publicly viewable (This may change)
2. This feature will not be utilized as an autosave feature
3. This feature will not benefit individuals who want to create personal drafts of a page
4. This feature will not benefit "preview" scenarios when trying to write complex DekiScript applications that rely on state of the current page

How it works

The drafts module will be built atop the MindTouch platform, utilizing three new API features (copy, "delete" a page/file revision, filter recent changes by namespace). The module will be sold as a part of the MindTouch Enterprise package. After the drafts module is installed in MindTouch, part of the set-up will entail setting up the /drafts/ root-level hierarchy, which is permissioned without BROWSE, so it does not show up search results, nav pane - essentially the page will exist, but never show up. (As a final implementation point, there is the possibility that an actual draft: namespace will be created for discoverability reasons)

The UI module will piggyback off of PHP hooks to inject custom views: view draft, edit draft, confirm publish, and find drafts. Custom work will be required to implement drafts into skinning, without making changes to the skinning engine.

From a end-user standpoint, the UI should give the impression that much like talk: pages, drafts exist as a 1:1 relationship to a page. The UI should mentally link these concepts visually in the skin (Figure 1). Each draft page has both a view & edit state - when in view state, the skin should maintain a visual cue of its different state. (Figure 2)

Figure 1: Default toolbar view of MindTouch with drafts enabled - "Draft page" appears

Figure 2: Default when you click "Draft page" - it is the view mode of drafts.
Visual indicators indicate an informational message as well as a title icon.

On systems which have installed drafts, users will be able to view the draft always by hitting a 'draft' link. For non-moderators, "edit page" will automatically load the draft for editing (as opposed to simply being disabled) - upon saving, the page will redirect to the draft view mode (with an explicit notice of it being appended to a queue of changes awaiting moderation) - see figure 3. For moderators, 'edit page' will maintain its original behavior - to edit a draft, moderators will have to explicitly go to the draft page and edit this page.

Figure 3: Edit mode of a system with drafts, for non-moderators

Figure 4: Upon successful save of a draft - redirects back to live version with a message

When a draft is edited, users will have an option of sending a notification to the moderator that this copy is ready for review and publishing - this notification does not lock the page - it simply is an email notification. Moderators will be able to also discover drafts through a specialized "Recent Drafts" view, which will show all drafts updated in reverse chronological order. 

On the view draft page, a "publish" link will appear in the toolbar for moderators - see figure 5. This will take the moderator to a confirmation view, which they will review the final view of the page, with a list of attributions or revisions (which one is utilized will be determined by the underlying spec) which the moderator will check or uncheck before sending the draft to the live copy.

Figure 5: Moderator's publish button in view mode of draft

Upon save, the files, tags, properties, will all be written back to the live copy. Attribution will be granted to the users/revs the moderator selected, and will appear in recent changes/revision history.

Open Questions

1. describe in pseudo-code how change to a draft would be applied to the published page
2. are all attachment revisions copied to original page if moderator chooses to publish all non-hidden revisions?
3. How to determine if an attachment on a draft with only one revision was uploaded by a user or copied during draft creation?
4. What should the permissions be for the drafts section? Should users be allowed to create pages there?

The following use cases describe how users and moderators create, edit, groom, and publish drafts

Use Case 1: User wants to edit a page for which there is no draft

1. user clicks on "edit draft" button on the page
2. the app creates the draft by copying the head revision of the current page, stores the page id, page path, and page revision
3. the app then checks if the current page has subscribers, if so it subscribes them to the newly created draft
4. the app then opens the draft in edit mode
5. when the user saves the draft, it notifies the subscribers about the change

Use Case 2: User wants to edit a page for which there is already a draft

1. user clicks on "edit draft" button on the page
2. the app then open the draft page in edit mode
3. when the user saves the draft, it notifies the subscribers about the change

Use Case 3: Moderator needs to change a page regardless if it has a draft or not

1. moderator clicks on "edit page"
2. the app then open the current page in edit mode
3. when the moderator clicks save, the changes are immediately applied to the page

Use Case 4: Moderator wants to publish a draft of a page that has not been modified since the draft was created

1. moderator goes to the draft
2. moderator views history of the draft
3. moderator removes any unwanted revisions from the draft (see page revision deletion below)
4. when the moderator clicks "publish", all non-deleted revisions are copied to the page, using the page id (see page copy below)
5. the app then deletes the draft page and redirects the moderator to the page

Use Case 5: Moderator wants to publish a draft of a page that has been modified since the draft was created

1. moderator goes to the draft
2. moderator views history of the draft
3. moderator removes any unwanted revisions from the draft (see page revision deletion below)
4. when the moderator clicks "publish", the app shows a warning message that the page has been modified since the draft was created with a link to view changes to the page since the draft was created. the app uses the page revision to determine if the draft is older
5. when the moderator clicks "accept", all non-deleted revisions are copied to the page, using the page id (see page copy below)
6. the app then deletes the draft page and redirects the moderator to the page

Use Case 6: Moderator wants to publish a draft of a page that has been deleted

1. moderator goes to the draft
2. moderator views history of the draft
3. moderator removes any unwanted revisions from the draft (see page revision deletion below)
4. when the moderator clicks "publish", the app shows a warning message that the page has been deleted since the draft was created
5. when the moderator clicks "confirm", all non-deleted revisions are copied to the page, using the page path (see page copy below)
6. the app then deletes the draft page and redirects the moderator to the page

Use Case 7: A user is finished with the draft and wants to let a moderator know that it is ready for review

1. user clicks the "ready for review" button on the draft
2. the app add the "ready" tag to the draft, which then shows the draft on the moderator dashboard

Use Case 8: Moderator deletes the draft page

1. moderator goes to the draft
2. moderator is able to delete the page
3. the draft can be recreated by a user with access and the previously deleted draft is not visible

Draft creation and storage

The preset location /drafts/{pageid} where {pageid} is the id of the original page is used for storage of draft pages. In the future, the draft may be in a draft: namespace similar to talk pages.

Permissions

Approach 1

• A 'draft editors' group is created and contains all users that are allowed to view and make draft changes. The role of this group does not include CHANGEPERMISSION.
• The /drafts page is set to private with a grant given to 'draft editors' allowing anyone in the group to view, create, and edit drafts.
• Guest users will not have access to /drafts because the Anonymous user is not a member of 'draft editors' and thus they will not be able to see or edit them

Approach 2

• The default contributor role given to all users does not include CHANGEPERMISSION.
• The homepage and profile pages are restricted as Semi-Public with a contributor grant given to the 'Moderator' group.
• The /drafts page has no restriction and no grants set.
• The Anonymous user has a Viewer role and will be able to see but not edit drafts. TODO: Would this be desirable?

Draft publishing

• Content is copied back to the original page including page text, page properties, tags, page title, and attachments. Refer to sections below for more details of the publish behavior with respect to these content elements.
• A public dialog is displayed allowing the moderator to choose the attribution method (refer below).
• If the original page has been modified since the creation of the draft, a warning will be displayed with a link to all revisions of the original that may not be reflected in the draft.
• Draft pages are deleted upon publish to allow users and moderators to tell what changes have been made in the draft since it was created.

Attribution

The publisher may decide if intermediate revisions of a draft should be copied or just the head revision. The publish dialog will give moderators a choice between the two methods.

Publish head revision only

• Head revision of draft is copied to the original page. Only the publisher gets the attribution on the new revision of the original page. Moderator can optionally hand write a comment attributing the authors of the draft.
• Keeps the history of the original page clean and brief but no attribution is given to draft editors other than the optional edit summaries.

Publish head revision for each attributed user

• The publish dialog shows the moderator list of potential users to attribute from the revision history of the draft.
• The head revision of the original page is recreated for each attributed user creating a revision for each user. The head revision of the draft is copied on top of this with the attribution going to the moderator.
• (This could be modified so that the head draft revision is copied for the moderator first and then each attributed user gets a revision of that copy as well.)

Publish all non-hidden revisions

• Moderator looks at the history of the draft and hides any revisions that have inappropriate or unwanted content
• All remaining visible revisions are copied to the original page with the original authors preserved
• Preserves the edits done by the moderator selected revisions and encourages users to clean up the draft before making edits if they don't want to risk their revision getting hidden. Encourages everyone to take part in moderation before making changes on top of inappropriate edits.

Attachments and Images

The draft page should look and feel as much as the original. A step of the draft creation process is to copy the head revision of all attached files from the original page to the new draft page. Any file links to the attachments on the original page will be changed to links of the corresponding images on the draft page. Copying these attachments has the following benefits:

• New uploads of referenced images located on the page will be reflected visually immediately.
• Dekiscript embedded within the page that relies on the current pages attachments will continue to function

The downside of this is that creating a draft in some cases may become a much more time consuming and intensive operation when many or large attachments exist.

Only head revision of new or updated attachments on the draft are moved back to the original page upon publish.

TODO: consider the above statement with regard for publishing the intermediate page revisions

Attachments on a draft that were copied from the original page are only moved back if they have more than one revision to not copy over attachments that were not modified.

TODO: How to determine if an attachment on a draft with only one revision was uploaded by a user or copied during draft creation?

TODO: Behavior for attachments that were copied to draft and then deleted in the draft.

Search

Drafts are indexed like any other page but may be hidden from search results naturally by permissions or explicitly by adding a search constraint: "-tag:draft" to the default site search

Moderation dashboard

TODO

1. how to create a dashboard of all existing drafts?
   • search for all pages with "tag:draft AND -tag:ready"
2. how to create a dashboard of all drafts that are in progress?
   • search for all pages with "tag:draft AND -tag:ready"
3. how to create a dashboard of all drafts ready to be published?
   • search for all pages with "tag:draft AND tag:ready"

Recent changes and feeds

TODO

Tags

Tags from the original page are copied to the draft when the draft is created. Upon publish, any new tags on the draft are copied to the original and any tags deleted on the draft that originated from the original page are removed from the original as well.

Page and File Properties

Page and file properties are copied from the original page to the draft when the draft is created. Upon publish, any new page and file properties on the draft are copied to the original and any properties deleted on the draft that originated from the original page are removed from the original as well.

Page Comments

Comments in the original page will not be included in created drafts.

Comments saved to a draft page will not be copied to the original page as part of a publish.

Notifications

Users may subscribe to changes of a draft page but no subscriptions are given automatically. The notification list of the original page is not copied to a draft. If a user subscribes to a draft that gets published and then recreated, since it's a new page the user will not be subscribed to the new draft.

Subpages

Creating a draft of an original page containing subpages will only make a draft of the original page itself and not its subpages.

Users may be allowed to make subpages under the draft page. These pages will not be included in the publish and will be deleted along with the draft after publish.

Page Display Title

The draft's display title is copied from the original page upon draft creation if the title has been set. Likewise, upon publish the latest display title of the draft is copied to the original page.

Page Language

If a language is set or changed on the draft, it will be set accordingly on the original page upon publish.

Draft Page Locking

A moderator has the ability to lock a page from being edited using the permission system or to only allow it to be edited by specific users. This may become useful for controversial content that is experiencing a lot of malicious edits.

Misc

1. should non-moderators see a visual clue that a page has an unpublished draft?

   • just use the moderator dashboard. no visual indication for an original page that a draft exists

Technical Requirements

Feature 1: Hide Page/File Revision

An administrator must be able to hide a page/file revision from the page/file history. A hidden page/file revision creates a gap in the page/file history and may not be retrieved via the API without admin access.  In other words, the content is gone for all practical purposes but the metadata for it is still available (original editor, timestamp).

Additional motivation: the ability to hide a page/file revision has come up to remove spam content from the site and has broader applicability.

Spec for page and file revision hiding

Feature 2: Page Revision Copy

The API must provide a feature to copy a given page revision to another location.  The page copy includes the page content, files, and properties as of that revision.  If the copied revision is the head revision, it will also copy the current tags of the page and title (since tags and title don't have revisions).  A page copy operation is essentially an export/import operation but optimized to operate within the same site.

Additional motivation: the ability to copy a page (usually head) to another location has broader applicability; it may also be used to create a better page revert since it would also revert content, properties, and files.

Feature 3 (optional): Page Feeds based on Tags or Search Queries

All a user to subscribe to a set of pages based on a search query or a list of tags (the latter is an optimization of the more general search query case).  The resulting feed is similar to the existing site feed or sub-tree feed, but only includes pages returned by the search queries or tag set.