X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/0efff4c683729e4d4e9ee120ade3b1183d1043ee..0750e137a5b855ffccab43496ec06691aec319e5:/packages/debbugs/debbugs.texi diff --git a/packages/debbugs/debbugs.texi b/packages/debbugs/debbugs.texi index 92e33e24a..8c70e26ad 100644 --- a/packages/debbugs/debbugs.texi +++ b/packages/debbugs/debbugs.texi @@ -8,7 +8,7 @@ @end direntry @copying -Copyright @copyright{} 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2011-2014 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -45,7 +45,7 @@ the Debian project but actually used also by the GNU project. The main distinctive feature of Debbugs is that it's mostly email-based. All actions on bug reports: opening, closing, changing the status, commenting, forwarding are performed via email by sending specially -composed letters to the partucular mail addresses. However, searching +composed letters to the particular mail addresses. However, searching the bug reports, querying bug report status and viewing comments have been web-based for a long time. To overcome this inconvenience the Debbugs/SOAP service was introduced. @@ -71,6 +71,7 @@ without addressing Debbugs' web interface. * Requesting bug numbers:: How to request bug report numbers. * Requesting bugs statuses:: How to request the status of bug reports. * Requesting messages:: How to get messages from bug reports. +* Requesting user tags:: How to request tags set by users. @end menu @node Installation @@ -165,9 +166,16 @@ Debbugs server the list of bug numbers that match a user's query. @defun debbugs-get-bugs &rest query This function returns a list of bug numbers that match the -@var{query}. @var{query} is a key-value pair sequence, where the key -is a keyword (symbol) and the value is a string. All queries are -logically concatenated via AND. +@var{query}. @var{query} is a sequence of keyword-value pairs where the +values are strings, i.e. :KEYWORD ``VALUE'' [:KEYWORD ``VALUE'']* + +The keyword-value pair is a subquery. The keywords are allowed to +have multiple occurrence within the query at any place. The +subqueries with the same keyword form the logical subquery, which +returns the union of bugs of every subquery it contains. + +The result of the @var{query} is an intersection of results of all +subqueries. Valid keywords are: @@ -176,6 +184,9 @@ Valid keywords are: The value is the name of the package a bug belongs to, like @code{"emacs"}, @code{"coreutils"}, @code{"gnus"}, or @code{"tramp"}. +@item :src +This is used to retrieve bugs that belong to source with given name. + @item :severity This is the severity of the bug. The exact set of available severities depends on the policy of a particular Debbugs port: @@ -194,8 +205,7 @@ An arbitrary string the bug is annotated with. Usually, this is used to mark the status of the bug. The list of possible tags depends on the Debbugs port. -Debian port: -@code{"patch"}, @code{"wontfix"}, @code{"moreinfo"}, +Debian port: @code{"patch"}, @code{"wontfix"}, @code{"moreinfo"}, @code{"unreproducible"}, @code{"fixed"}, @code{"potato"}, @code{"woody"}, @code{"sid"}, @code{"help"}, @code{"security"}, @code{"upstream"}, @code{"pending"}, @code{"sarge"}, @@ -203,11 +213,15 @@ Debian port: @code{"confirmed"}, @code{"ipv6"}, @code{"lfs"}, @code{"fixed-in-experimental"}, @code{"fixed-upstream"}, @code{"l10n"}, @code{"etch"}, @code{"etch-ignore"}, @code{"lenny"}, -@code{"lenny-ignore"}. +@code{"lenny-ignore"}, @code{"squeeze"}, @code{"squeeze-ignore"}, +@code{"wheezy"}, @code{"wheezy-ignore"}. The actual list of tags can be +found on @uref{http://www.debian.org/Bugs/Developer#tags}. -GNU port: -@code{"fixed"}, @code{"notabug"}, @code{"wontfix"}, -@code{"unreproducible"}, @code{"moreinfo"}, @code{"patch"}. +GNU port: @code{"fixed"}, @code{"notabug"}, @code{"wontfix"}, +@code{"unreproducible"}, @code{"moreinfo"}, @code{"patch"}, +@code{"pending"}, @code{"help"}, @code{"security"}, @code{"confirmed"}. +See @url{http://debbugs.gnu.org/Developer.html#tags} for the actual list +of tags. @item :owner This is used to identify bugs by the owner's email address. The @@ -220,19 +234,44 @@ With this keyword it is possible to filter bugs by the submitter's email address. The special email address @code{"me"} is used as pattern, replaced with the variable @code{user-mail-address}. +@item :maint +This is used to find bugs of the packages which are maintained by the +person with the given email address. The special email address +@code{"me"} is used as pattern, replaced with @code{user-mail-address}. + +@item :correspondent +This allows to find bug reports where the person with the given email +address has participated. The special email address @code{"me"} is used +as pattern, replaced with @code{user-mail-address}. + +@item :affects +With this keyword it is possible to find bugs which affect the package +with the given name. The bugs are chosen by the value of field +@code{affects} in bug's status. The returned bugs do not necessary +belong to this package. + +@item :status +Status of bug. Valid values are @code{"done"}, @code{"forwarded"} and +@code{"open"}. + @item :archive -A keyword to filter for bugs which are already archived, or not. -Valid values are @code{"0"} (not archived), @code{"1"} (archived) or +A keyword to filter for bugs which are already archived, or not. Valid +values are @code{"0"} (not archived), @code{"1"} (archived) or @code{"both"}. If this keyword is not given in the query, @code{:archive "0"} is assumed by default. @end table -Example. Get all bug reports that were initiated by me. +Example. Get all opened and forwarded release critical bugs for the +packages which are maintained by @code{"me"} and which have a patch: @example -(let ((debbugs-port "gnu.org")) - (debbugs-get-bugs :submitter "me" :archive "both")) -@result{} (5516 5551 5645 7259) +(let ((debbugs-port "debian.org")) + (debbugs-get-bugs :maint "me" :tag "patch" + :severity "critical" + :status "open" + :severity "grave" + :status "forwarded" + :severity "serious")) @end example @end defun @@ -469,4 +508,55 @@ Note, that mbox downloading will work only if the specified (@pxref{Configuration}). @end defun +@node Requesting user tags +@chapter Requesting user tags + +A user tag is a string, a user has assigned to one or several bugs. +The user is identified by an email address. The port @code{"gnu.org"} +uses also package names as user identification. + +@defun debbugs-get-usertag &rest query +Return a list of bug numbers which match @var{query}. + +@var{query} is a sequence of keyword-value pairs where the values are +strings, i.e. :KEYWORD ``VALUE'' [:KEYWORD ``VALUE'']* + +Valid keywords are: + +@table @code +@item :user +The value is the name of the package a bug belongs to, like +@code{"emacs"}, @code{"coreutils"}, or @code{"tramp"}. It can also be +an email address of a user who has applied a user tag. The special +email address @code{"me"} is used as pattern, replaced with +@code{user-mail-address}. There must be at least one such entry; it +is recommended to have exactly one. + +@item :tag +A string applied as user tag. Often, it is a subproduct +identification, like @code{"cedet"} or @code{"tramp"} for the package +@code{"emacs"}. +@end table + +If there is no @code{:tag} entry, no bug numbers will be returned but +a list of existing user tags for @code{:user}. + +Example. Get all user tags for the package @code{"emacs"}: + +@example +(let ((debbugs-port "gnu.org")) + (debbugs-get-usertag :user "emacs")) +@result{} ("www" "solaris" "ls-lisp" "cygwin") +@end example + +Get all bugs tagged by package @code{"emacs"} with @code{"www"} or +@code{"cygwin"})): + +@example +(let ((debbugs-port "gnu.org")) + (debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin")) +@result{} (807 1223 5637) +@end example +@end defun + @bye