{-| This module provides a short tutorial on how to use DPM. Suppose that Dave Developer implements a very cool feature. After polishing his patch, Dave uses @darcs send@ to send the patch: > $ darcs send host:MAIN_REPO > Tue Mar 16 16:55:09 CET 2010 Dave Developer <dave@example.com> > * very cool feature > Shall I send this patch? (1/1) [ynWsfvplxdaqjk], or ? for help: y > Successfully sent patch bundle to: patches@example.com After the patch has been sent to the address @patches\@example.com@, DPM comes into play. For this example, we assume that mail devivery for @patches\@example.com@ is handled by some mailfilter program such as maildrop (<http://www.courier-mta.org/maildrop/>) or procmail (<http://www.procmail.org/>). The task of the mailfilter program is the add all patches sent to @patches\@example.com@ to the DPM database. This is achieved with the DPM command @add@: > $ dpm add --help > add: Put the given patch bundles under DPM's control (use '-' to read from stdin). > Usage: add FILE... > > Command options: > > Global options: > -r DIR --repo-dir=DIR directory of the darcs repository > -s DIR --storage-dir=DIR directory for storing DPM data > -v --verbose be verbose > --debug output debug messages > --batch run in batch mode > --no-colors do not use colors when printing text > --user=USER current user > --from=EMAIL_ADDRESS from address for emails > --review-address=EMAIL_ADDRESS email address for sending reviews > -h, -? --help display this help message Now suppose that Dave's patch is in the DPM database. A reviewer, call him Richard Reviewer, uses the DPM command @list@ to see what patches are available in this database: > $ dpm list --help > list: List the patches matching the given query. > > Query ::= Query ' + ' Query -- logical OR > | Query ' ' Query -- logical AND > | '^' Query -- logical NOT > | '{' Query '}' -- grouping > | ':' Special > | String > > Special is one of "undecided", "rejected", "obsolete", "applied", > "reviewed", "open", or "closed", and String is an arbitrary sequence > of non-whitespace characters not starting with '^', '{', '}', '+', or ':'. > > If no query is given, DPM lists all open patch groups. > > Usage: list QUERY ... > > Command options: > > Global options: > -r DIR --repo-dir=DIR directory of the darcs repository > -s DIR --storage-dir=DIR directory for storing DPM data > -v --verbose be verbose > --debug output debug messages > --batch run in batch mode > --no-colors do not use colors when printing text > --user=USER current user > --from=EMAIL_ADDRESS from address for emails > --review-address=EMAIL_ADDRESS email address for sending reviews > -h, -? --help display this help message In our example, the output of the list command might look as follows: > $ dpm -r MAIN_REPO -s DPM_DB list > very cool feature [State: OPEN] > 7861 Tue Mar 16 17:20:45 2010 Dave Devloper <dave@example.com> > State: UNDECIDED, Reviewed: no > added > some other patch [State: OPEN] > 7631 Tue Mar 16 13:15:20 2010 Eric E. <eric@example.com> > State: REJECTED, Reviewed: yes > added > ... (The @-r@ option specifies a directory containing the DPM database. Initially, you simply create an empty directory. The @-s@ option specifies the path to the darcs repository in question.) DPM groups all patches with the same name inside a /patch group/. Patch groups allow keeping track of multiple revisions of the same patch. In the example, the patch group of name /very cool feature/ has only a single member, which is the patch Dave just created. The patch is identified by a unique suffix of its hash (7861 in the example). The output of the list command further tells us that no reviewer decided yet what to do with the patch (its in state UNDECIDED). At this point, Richard Reviewer reviews Dave's patch. During the review, he detects a minor bug so he rejects the patch: > $ dpm -r MAIN_REPO -s DPM_DB review 7861 > Reviewing patch 7861 > Starting editor on DPM_DB/reviews/2010-03-16_7861_swehr_24166.dpatch > <inspect patch in editor> > Mark patch 7861 as reviewed? [Y/n] y > Patch 7861 is in state UNDECIDED, reject this patch? [y/N] y > Enter a comment: one minor bug > Marked patch 7861 as reviewed > Moved patch 7861 to REJECTED state > Send review to Dave Developer <dave@example.com>? [Y/n] y > Mail sent successfully. Now Dave Developer receives an email stating that has patch has been rejected. The email also contains the full review so that Dave sees why the patch has been rejected. Thus, Dave starts fixing the bug, does an @amend-record@ of the patch, and finally sends the patch again: > $ darcs send MAIN_REPO > Tue Mar 16 16:55:09 CET 2010 Dave Developer <dave@example.com> > * very cool feature > Shall I send this patch? (1/1) [ynWsfvplxdaqjk], or ? for help: y > Successfully sent patch bundle to: patches@example.com Once the email is received, the improved patch is added to the DPM database. The output of the @list@ command now looks like this: > $ dpm -r MAIN_REPO -s DPM_DB list > very cool feature [State: OPEN] > 2481 Tue Mar 16 17:50:23 2010 Dave Devloper <dave@example.com> > State: UNDECIDED, Reviewed: no > added > 7861 Tue Mar 16 17:20:45 2010 Dave Devloper <dave@example.com> > State: REJECTED, Reviewed: yes > marked as rejected: one minor bug > some other patch [State: OPEN] > 7631 Tue Mar 16 13:15:20 2010 Eric E. <eric@example.com> > State: REJECTED, Reviewed: yes > added > ... The patch 2481 is the improved revision of the original patch 7861. It is in the same group as the original patch because both patches have the same name. Richard Reviewer reviews the improved patch and has no complains anymore: > $ dpm -r MAIN_REPO -s DPM_DB review 2481 > Reviewing patch 2481 > Starting editor on DPM_DB/reviews/2010-03-16_2481_swehr_876102.dpatch > <inspect patch in editor> > Mark patch 2481 as reviewed? [Y/n] y > Patch 2481 is in state UNDECIDED, reject this patch? [y/N] n > Enter a comment: ok > Marked patch 2481 as reviewed > Send review to Dave Developer <dave@example.com>? [y/N] n At this point, Richard Developer applies the patch with the very cool feature: > $ dpm apply 2481 > About to apply patch 2481 > Entering DPM's dumb (aka interactive) apply command. > Future will hopefully bring more intelligence. > > Instructions: > ============= > - Press 'n' until you reach > Tue Mar 16 17:50:23 2010 Dave Devloper <dave@example.com> > * very cool feature > (Hash: 20100316162041-c71f4-871aedab8f4dd3bd042b9188f1496011c7dd2481) > - Press 'y' once > - Press 'd' > > Tue Mar 16 17:50:23 2010 Dave Devloper <dave@example.com> > * very cool feature > Shall I apply this patch? (1/1) [ynWsfvplxdaqjk], or ? for help: y > Finished applying... > Patch 2481 applied successfully > Send notification to author Dave Developer <dave@example.com> of patch 2481? [Y/n] y > Mail sent successfully. Applying a patch closes the corresponding patch group. Per default, the @list@ command doesn't display closed patch groups, but we can force it to do so with the @:closed@ query: > $ dpm list :closed > very cool feature [State: CLOSED] > 2481 Tue Mar 16 17:50:23 2010 Dave Devloper <dave@example.com> > State: APPLIED, Reviewed: yes > marked as applied: - > 7861 Tue Mar 16 17:20:45 2010 Dave Devloper <dave@example.com> > State: REJECTED, Reviewed: yes > marked as rejected: one minor bug > ... -} module DPM.Tutorial where foo = foo