This is a first-draft version of the Debbugs API changes needed to finish the project originally described in DavidWendt/GSOC2010Proposal. I welcome comments; I want this API to be useful and easy.

New API calls

The SOAP API shall be extended to add functions to bring the SOAP API to parity with the existing E-mail API.

Since all write access has been predicated on the e-mail API, SOAP API functions must contain a few parameters to match. These common parameters will be used as the contents of particular e-mail headers when bugs are viewed on the website or in mbox format.

As a convention, variable types will be denoted with Perl sigils.

Common e-mail parameters

$comment,
$sender_email, #Must be a valid e-mail address
$subject

$sender_email is the e-mail address of the person making the API request. It will be used in the From: field on all messages generated from API requests. Likewise, $subject is the e-mail subject to use for the Subject: field in the message.

Additionally, you can also place a $comment with your call; the $comment variable will hold what would normally be placed after 'thanks' in a control message or after the psuedo-headers in a submit message.

Example usage

Since many of these functions are already extant control@bugs.debian.org functions, I have designed them to 'line up' with their e-mail counterparts in a way that makes mental sense. As such, their descriptions are rough paraphrases of the control documentation and the API will accept variable arguments wherever the e-mail system does.

For example, to apply tags to a bug using e-mail, you would write:

From: me@example.com
To: control@bugs.debian.org
Subject: Re: Buffer overflow in 'hello' package

#This is not a severe bug
severity 1842311 minor
tags 1842311 + fixed
thanks

Fix is pending

While, using the API, one would use the call:

tags("1842311", "+", qw(fixed), "Fix is pending", "me@example.com", "");
severity("1842311", "minor", "This is not a severe bug", "me@example.com", "");

There are two control functions which have been changed in the API: Clone now generates and returns new bug ID numbers. The package statement, used as a safety filter for e-mail control, does not have an API equivalent.

API reference

Reportbug: File a bug report.

$bug_id = reportbug($package,
          $version,
          %psuedo_headers = (Severity => "normal", #must be a valid severity level
                             Tags => qw(fixed-upstream), ...),
          $loudness, #Must be: "default", "quiet", "maintonly", or a null string
          $comment,
          $sender_email, #Must be a valid e-mail address
          $subject);

Creates a new bug report. The new bug ID will be returned. $comment will be used for the bug description.

$package and $version are quite self-explainatory, they are what you would normally put in the

%psuedo_headers contains all of the additional psuedo-headers that the e-mail system will accept, like Severity, Tags, User, Usertags, Forwarded, Owner, and Source. X-Debbugs-CC can also be used here to send copies of a submitted bugreport to other users.

$loudness indicates what level of announcement the new bug will recieve; it mirrors the use of quiet and maintonly submission addresses. "default" (or a blank string) will treat the bug as a normal submission and forward the report to all interested parties. "maintonly" will only send the report to the package maintainer. "quiet" will only file the report without sending to any third parties.

$bug_id will be returned if the bug posting was successful. It is a long-lived identifier to refer to a bug.

Followup: Comment on a bug.

$message_id = followup($bug_id,
              $loudness, #Must be "default", "quiet", "maintonly", "submitter", or blank
              $comment,
              $sender_email, #Must be a valid e-mail address
              $subject);

Send a followup comment message to a bug. $comment will be used as the message text. $loudness indicates who this followup should be sent to and works similarly to the reportbug call. You can also set $loudness to "submitter" which only sends the followup to the bug submitter. This function returns the $message_id.

Reassign: Change the package and version assignments.

reassign($bug_id,
         $package,
         $version, #Must be either a valid version or a null string
         $package, $version...,
         $comment,
         $sender_email, #Must be a valid e-mail address
         $subject);

$package is the new package this bug should be noted as affecting. If a bug can be fixed by changing one of a number of packages, you may send multiple $package names, with a following $version parameter. $version may be a blank string, in which the bug affects all versions of a particular package.

Reopen: Reopen a closed bug.

reopen($bug_id,
       $new_originator, #A valid e-mail address, or "!", or "="
       $comment,
       $sender_email, #Must be a valid e-mail address
       $subject);

$new_originator is the new bug originator. If it is "=" or a blank string, the new bug originator will be the original one. If it is "!", it will be the $sender_email common parameter, i.e. you will become the new originator. In any other case $new_originator will be treated like an e-mail address.

Found: Change the versions a bug affects

found($bug_id,
      $version, $version..., #Variable argument: send any number of versions
      $comment,
      $sender_email, #Must be a valid e-mail address
      $subject);

notfound($bug_id,
         $version, $version..., #Variable argument: send any number of versions
         $comment,
         $sender_email, #Must be a valid e-mail address
         $subject);

Change the versions a bug affects. $version is the version affected/not-affected, you may send more than one to perform multiple changes in batch.

Fixed: Change the versions a bug is fixed in

fixed($bug_id,
      $version, $version..., #Variable argument: send any number of versions
      $comment,
      $sender_email, #Must be a valid e-mail address
      $subject);

notfixed($bug_id,
      $version, $version..., #Variable argument: send any number of versions
      $comment,
      $sender_email, #Must be a valid e-mail address
      $subject);

Like found/notfound, except that instead of adding or removing package versions, it will instead mark package versions as fixed or not fixed.

Submitter: Change the submitter/originator of a bug

submitter($bug_id,
          $new_originator, #Valid e-mail address or "!"
          $comment,
          $sender_email, #Must be a valid e-mail address
          $subject)

The parameters are the same as described in reopen, except $new_originator may not be "=".

This function changes the originator of only $bug_id, and not any bugs merged with $bug_id, as specified in the BTS server control documentation.

Forwarded: Mark a bug as forwarded to upstream.

forwarded($bug_id,
          $upstream_url,
          $comment,
          $sender_email, #Must be a valid e-mail address
          $subject);

notforwarded($bug_id,
             $comment,
             $sender_email, #Must be a valid e-mail address
             $subject);

Marks $bug_id as having been forwarded to $upstream_url, but does not actually forward anything. Notforwarded removes any notifications that $bug_id was forwarded to any $upstream_url.

Retitle: Change the name of a bug.

retitle($bug_id,
        $new_title,
        $comment,
        $sender_email, #Must be a valid e-mail address
        $subject);

Change the title of $bug_id. $new_title is the new title.

Severity: Change the severity of a bug.

severity($bug_id,
         $severity, #A valid severity level from critical to wishlist.
         $comment,
         $sender_email, #Must be a valid e-mail address
         $subject);

Change $bug_id's severity. $severity must be a valid severity level as specified in the Debbugs documentation.

Affects: Change what packages a bug affects

affects($bug_id,
        $action, # + for add, - for remove, = for set
        @packages, #optionally, $package for a single affected package
        $action, @packages..., #Multiple actions can be batched together.
        $comment,
        $sender_email, #Must be a valid e-mail address
        $subject);

Mark certain packages as being affected or remove marks of packages being affected by $bug_id. $action is a string of either "+", which marks $package as affected, or "-" which unmarks $package as affected, or "=", which marks $package as affected and unmarks all other packages. @packages can be used, as a list of $package names to mark or unmark as appropriate. You can send multiple pairs of $action and $package to perform multiple actions.

Summary: Change the main bug description.

summary($bug_id,
        $message_id,
        $comment,
        $sender_email, #Must be a valid e-mail address
        $subject);

Change $bug_id's summary to the first paragraph of $message_id's non-psuedoheader part. Alternatively, if $message_id is blank, remove the message summary.

Clone: Duplicate a bug.

@new_bugs = clone($bug_id,
            $number_of_new_bugs,
            $comment,
            $sender_email, #Must be a valid e-mail address
            $subject);

Create duplicates of $bug_id, in case a particular bug is actually several things to be fixed independantly. The way this function works has been modified to avoid complicating the API. In the control system, one specified temporary, negative ID numbers to be used in later commands in the same e-mail. However, there is no way to determine what a negative bug ID is referring to in subsequent calls. Instead, clone takes a $number_of_new_bugs parameter which determines how many new bugs are to be cloned from $bug_id. The new bug IDs are returned as an array of bug IDs.

Merge: Merge bug reports together.

merge($bug_id, $bug_id...,
      $comment,
      $sender_email, #Must be a valid e-mail address
      $subject);

forcemerge($bug_id, $bug_id...,
           $comment,
           $sender_email, #Must be a valid e-mail address
           $subject);

unmerge($bug_id,
        $comment,
        $sender_email, #Must be a valid e-mail address
        $subject);

Cause the bugs in the list of $bug_id params to be treated as the same bug. In such a state, all opens, closes, forwardings, notforwardings, and reassigns will apply to all of the merged bugs as if they were the same bug. Bugs must be in the same open/closed, forwarded/notforwarded, assigned, and severity states, otherwise the merge will fail.

Forcemerge will instead force every bug to have the first bug's states. This will fail if the bugs listed are not in the same package. This can have the affect of closing bugs by merging.

Unmerge disconnects a bug from any bugs it may be merged with. It does not undo an entire merge.

Tag: Set tags for a bug.

tag($bug_id,
    $action, #same as affects, + for add, - for remove, = for set
    @tags, #optionally, will accept a string instead of an array for a single tag
    $action, @tags...,
    $comment,
    $sender_email, #Must be a valid e-mail address
    $subject);

An $action is either + (add tag), - (remove tag), or = (set tags to exactly), followed by a $tag which can be either a scalar or arrayref of tags to apply. All tags must be a valid Debbugs tag. You may add multiple tags by sending multiple $action and @tags pairs.

Block: Mark a bug as being blocked by another bug

block($bug_id,
      $blocker_bug, $blocker_bug...,
      $comment,
      $sender_email, #Must be a valid e-mail address
      $subject);

unblock($bug_id,
        $blocker_bug, $blocker_bug...,
        $comment,
        $sender_email, #Must be a valid e-mail address
        $subject);

Mark that $bug_id cannot be fixed until the bugs $blocker_bug, $blocker_bug... have been fixed.

Changeowner: Change the owner of a bug (or disown it)

owner($bug_id,
      $email_address, #valid e-mail or "!"
      $comment,
      $sender_email, #Must be a valid e-mail address
      $subject);

noowner($bug_id,
        $comment,
        $sender_email, #Must be a valid e-mail address
        $subject);

The Owner call will change the owner of a bug to $email_address. In the case where $email_address is the string "!", the bug will be reassigned to you.

Noowner will remove all bug owners; i.e. no one claims special responsibility for fixing a bug aside from the current package maintainer.

Archive: Force a bug to be archived

archive($bug_id,
        $comment,
        $sender_email, #Must be a valid e-mail address
        $subject);

unarchive($bug_id,
         $comment,
         $sender_email, #Must be a valid e-mail address
         $subject);

Archive and unarchive $bug_id, as specified in the server-control documentation.

Done: Mark a bug as fixed

done($bug_id,
     @versions, #List of versions which contain the fix
     $comment,
     $sender_email, #Must be a valid e-mail address
     $subject);

Imitates the functionality of sending an e-mail to nnnn-done@bugs.debian.org; The common $comment will be used as explaination of why the bug is being closed. @versions will list the version or versions which have been fixed.