[development] deletion API summary, question

[Chad Phillips -- Apartment Lines]

as i mentioned a short time ago, i've been trying to flesh out a  
deletion API for drupal.  i thought i'd take a few minutes and  
discuss it's current state, and throw out some unfinished business to  
get perspective from other developers.

in working on the trashbin patch, i discovered that it's helpful to  
think of deletions as happening in packages.  when you delete a node,  
you don't just delete something from the node table--there are   
related node tables, then hook_delete calls, then nodeapi delete  
calls (and possibly other calls initiated from the last two in that  
list). deletions in drupal proceed from the top down, recursing until  
all items are deleted.  that's what i'm calling a package.

my current work is based on that viewpoint. package deletions are  
started with a call to a helper function (called  
drupal_delete_package at the moment), all relevant deletion  
operations are passed into the package via drupal_delete, and then  
packages are deleted via another helper function  
(drupal_delete_execute).

once a package is compiled, there are two hooks that are called:

hook_delete_pre -- this is an opportunity for modules to throw  
objections to a package deletion.  any module calling this hook will  
have access to the information in the entire deletion package, and  
can throw two kinds of objections: confirm and abort.

hook_delete_execute -- this is an opportunity for modules to perform  
any last minute operations before the package is deleted.  for  
example, a trashbin module would use this hook to store metadata  
about the package deletion.

workflow is as follows:

1. call drupal_delete_package to start the package
2. call drupal_delete as many times as is necessary to fill the  
package with deletion data
3. call drupal_delete_package again if you wish to start a new  
deletion package in the same page call (like for admin/node multi- 
deletes)
4. call drupal_delete_execute to execute the deletion of all packages
5. hook_delete_pre is called, and modules put in confirm and abort  
objections
6. if there are any confirm objections, then a confirm screen is  
generated
7. once confirmed, the packages are resubmitted
8. any packages with abort objections are skipped, and warnings are  
issued
9. remaining packages are deleted

whew!

the important remaining question:

how are we to perform the actual deletions?  do we delete the data  
from the table, or merely mark it as deleted with the addition of a  
'deleted' column to all tables?  if we're going to take the latter  
approach, it's important to note that we can't just have a DELETED  
flag--we need some way to know which deletions belong to which  
packages, otherwise it's a real mess  :)  my suggestion is to record  
a unique package id in the deleted column for each deleted package.

sorry for the long post--this is a big job and a relatively complex  
feature--there's a lot to say!

chad