Drupal undelete - SoC 2007 proposal

Synopsis
My proposal is for a Drupal 'undelete' module: a module which provides node content- and node content admin- modules with a standard API for implementing operations for restoring deleted nodes, and therefore provides a Drupal site end-users and admins with a well-understood piece of functionality, through which common paradigms like a node 'trashbin' can be implemented. The ability to restore a previously deleted piece of content is a major advance for Drupal functionality-wise, and one much requested and desired. It will lay the groundwork and may even find time for natural extensions like 'un-edit', 'un-insert' – pieces of a general functionality for 'undoing' content operations, like that found in the Plone CMS. It will also be an advance architecture-wise, as it will stimulate activity and consensus in the Drupal developer community around ambiguous or only partially-specified pieces of Drupal architecture; like what defines a content 'operation', content 'delete', relations among content nodes, content operation 'transactions' across modules, content node data storage; down to a clearer idea of what an piece of Drupal content should look like in code. However, the module will not require changes in any way to the current Drupal core and node handling code, nor in any existing Drupal database objects. One overriding design principle for undelete is that it be implemented as an independent, self-contained module, which modules may choose to use and implement as additional functionality that does not require any changes to existing code – undelete will install only new database objects and code. It will not require rewrites of any existing PHP or SQL code and will not attempt to use hook_nodeapi to inject SQL code for modifying node data without knowledge of the node module. Although differing in several key approaches. The undelete module builds on the work being done on the Drupal 'delete'API' and 'trashbin' code by Chad Phillips, which has been in development (and debate) for more that 1 ½ years.

I. Introduction
My proposal is for a Drupal 'undelete' module: a module which provides node content- and node content admin- modules with a standard API for implementing operations for restoring deleted nodes, and therefore provides a Drupal site end-users and admins with a well-understood piece of functionality, through which common paradigms like a node 'trashbin' can be implemented. The ability to restore a previously deleted piece of content is a major advance for Drupal functionality-wise, and one much requested and desired. It will lay the groundwork and may even find time for natural extensions like 'un-edit', 'un-insert' – pieces of a general functionality for 'undoing' content operations, like that found in the Plone CMS. It will also be an advance architecture-wise, as it will stimulate activity and consensus in the Drupal developer community around ambiguous or only partially-specified pieces of Drupal architecture.

II. Background
The undelete functionality for Drupal was first proposed by Chad at Drupal Conference 2005 as part of a revamp for the Drupal delete cycle A preliminary hook_delete_confirm was first coded by Chad as a way to inject confirmation and custom steps into the node delete process (http://drupal.org/node/26649) . Then this was expanded in his undo patch to then current 4.7 HEAD in July 2006 (http://drupal.org/node/35422). Undo was a very large patch, which modified many core node modules node_delete to move nodes to a another table instead of permanently deleting them. Although well received, the large scope of the patch meant a constant revision process to keep up with the constant stream of breaking changes in core HEAD. There was also opposition in the developer community to inclusion of this new functionality in core, debates on approaches, and concerns over an inconsistent user experience. After the last breaking change, Chad stopped work on the patch and focused on a new API for delete, to be possibly part of Drupal 6.

III. Motivation and benefits
Apart from the significant functionality undelete will add to Drupal, successful implementation of the module will provide developers with insight and consensus over node operations and data storage. A possible answer to the question on what the 'delete content' operation means and how this definition is specified in code so that all content uses this definition will be proposed. For example, if I create an event which links to a page, then the event node data is physically linked with the page node, but if the page node is restored, should the event node data and link also be restored? Right now in the Drupal architecture, there is no abstraction of node, node state, node operations, and transactions. Successful implementation of undelete will be valuable for future implementation of these architecture pieces. That said, there will be no recommendations or attempts to change the current architecture; rewrite the entire Drupal codebase, or even a tiny bit, using language x and development paradigm y. What the undelete activity will to is explore the edge of the current Drupal software architecture. Some future architect, may pull this project's mailing list activity out of the archive to support their vision.

IV. Implementation
My implementation for undelete will build on Chad's work on undo, delete andtrashbin – but there are significant differences. The undelete module is implemented in the following:
1.It would be doable, and I believe better at this stage, if undelete could be implemented completely independently from core. The new delete API is a complex revamp that like any new API will see its share of errors in initial implementation . I'd rather have a mdoule's undelete broken, than normal delete being broken. Basically I envision working at the problem from two ends – Chad with delete API and trashbin; and my own module, borrowing much from Chad's work, but keeping it independent. If delete API makes it into Drupal 6 then undelete will use it. But I think that undelete is something that could be released for Drupal 5, and that the delete API would greatly benefit by another project taking a crack at some of the core issues from another angle.
2.Modules implementing undelete will generate Drupal PHP code for the restore operations, not SQL code. The basic idea is that each module knows best how to restore a node, using its own functions. Deleting a node which implements undelete requires the node module to store a PHP script in the undelete module storage, which can be executed to restore the node.
3.The thorniest bits of undelete deal with the whole problem of restoring nodes that are exact 1:1 matches with the deleted notes – all dependent data like related nodes, events, taxonomy terms, must also be restored. This may be the ideal case, and necessary in many instances, but it is very useful for a module to be able to undelete by simply creating a new node with only the data from the previous deletion restored. A node_delete_undelete_new hook provides a way for a module to recreate a deleted node's data as a completely new node.
4.A simple forms-based user interface, similar to the log UI, displays a list of deleted items per user, with actions to restore or permanently delete selected nodes. A menu item for this page, labelled 'Undelete' will be placed under the create content menu item.
5.The module will implement access control, defining which users and roles if any, are allowed to view and restore deleted from other users.

V. Milestones and deliverables (updated)
My implementation plan for undelete is to iterate a set of core activities – research, design, coding, testing – every 2 weeks. There should be at least 4 releases of code + project outputs prior to the official August 20th release and evaluation.
M0: Kickoff
Period: now - 28th May
Activities:
1.Setup site with last working version of 4.7 trashbin patch.
2.Setup site with current delete API and trashbin module, and help out with testing, comments, docs.
3.Study main features of delete API like delete cycle and delete 'packages'.
4.Research undelete and undo patterns like command objects; existing CMS implementations.
Deliverables:
1.Create project site with initial ideas, concepts, research, discussion
2.Document: story/wiki on undelete patterns and implementations

M1: Requirements and Specifications, Proof-of-concept
Period: 28th May - June 11th
Activities:
1.Start discussion and obtain preliminary consensus on undelete requirements and specification from Drupal devel community and architects.
2.Implement undelete for node_example module using delete API / trashbin
Deliverables (deadline June 11):
1.Document – Drupal undelete preliminary requirements and specification
2.Code – working undelete for node_example module using delete API / trashbin

M2: Initial undelete module code
Period June 11th - June 25th
Activities:
1.Draft design for new undelete module.
2.Implement preliminary module code
3.Implement undelete for node_example module using new undelte code
4.Release initial code to testing volunteers / evaluators
5.Document ongoing community discussion on undelete requirements and specs
Deliverables (deadline June 25th):
1.Code - First code for undelete module defining hook_node_undelete, hook_node_undelete_new and hook_node_association_restore.
2.Code - First implementation of undelete in node_example module
3.Document – Undelete module design.

M3: First official code release
Period: June 25th - July 9th
Activities:
1.Document feedback, suggestions
2.Freeze specification for undelete module
3.Implement code for first public release from project
Deliverables (deadline July 9th):
1.Document – Final undelete module specification.
2.Code – First official release of project code uploaded to Google server
Project evaluation: July 9th - 16th
M4: July 16th - July 30th feedback, code, test, document- 3rd module code release
M5: July 30th - August 13th feedback, code, test, document - 4th module code release
M6: August 13th - August 20th – Final project coding cycle, final code release to Google , final evaluation

VI. Interop with hunmonks delete API/trashbin (new)
hunmonk's delete API exposes hook_delete_execute() which allows modules access to delete 'packages', right before they are processed for deletion. Undelete can implement this to copy and log all data scheduled for deletion . A simple example: in the original 4.7 trashbin patch, there was a simple clever operation in system_trash() to select and copy the rows scheduled for deletion - in each DELETE query, simply replace DELETE with SELECT * FROM. If the new delete API makes it into core, it offers the hook and data structures for an undelete/trashbin module without requiring any further core patches.

That said, my proposal was to approach undelete using both the delete API,and also with my own ideas. hunmonk's API will show up at earliest in 6.x and every module will have to reimplement delete. But I want to build a undelete module for 5.x, which doesn't require any core patches , and doesn't require any changes to existing delete. Much of the logic will come from Chad's work, especially on packages, but there are some ideas of my own. I want to implement undelete as a set of hooks - hook_node_undelete, hook_node_association_restore... One key idea is instead of node modules passing a SQL delete query and having undelete build a SELECT/INSERT statement from this query, I would have the node modules pass in Drupal PHP code, to actually perform the node undelete operation.

So undelete will be implemented using hunmonk's upcoming delete API + new trashbin code, but I also want to code an independent implementation that could be used in 5.x.