UPGRADE.md

   1 # Debbugs upgrade notes #
   2
   3 ## From 2.4.2 to 2.6 ##
   4
   5 Debbugs configuration file now sets default values for all configuration file
   6 options, so if you're upgrading from earlier versions, you do not need to
   7 specify values for the new configuration files.
   8
   9 ### Templates ###
  10
  11 Debbugs now uses Text::Template for templates, and any of the existing templates
  12 can be overridden by creating a new directory and setting `$gTemplateDir` to the
  13 new directory.
  14
  15 ## From 2.4.1 to 2.4.2 ##
  16
  17 The file format used to store the status of a bug (package, severity, etc.)
  18 has changed; it is now in an RFC822-like format in order to be more
  19 extensible, and is written to .summary files rather than the old .status
  20 files. Before accepting any mail with the new version of debbugs, you must
  21 run the 'debbugs-upgradestatus' program over your bug spool. The old .status
  22 files will be left intact, and will continue to be written in sync with the
  23 .summary files for compatibility with external tools.
  24
  25 There is a new standalone spam-scanning script called spamscan, which uses
  26 the SpamAssassin modules. To use it, set the `$gSpamScan` variable in
  27 `/etc/debbugs/config` to a true value and `$gSpamMailbox` to an mbox file to
  28 which detected spam should be appended, add /usr/lib/debbugs/spamscan to
  29 your crontab as per the example, and optionally set `$gSpamRulesDir` and
  30 `$gSpamLocalTestsOnly` as desired.
  31
  32 ## From 2.4 to 2.4.1 ##
  33
  34 Add the following variables to the /etc/debbugs/config file:
  35
  36 `$gHTMLSuffix = ".html";`
  37
  38 The use of `$gCGIDomain` has been cleaned up; formerly, it needed to begin
  39 with "http://", which was confusingly inconsistent with all the other domain
  40 variables. If you worked around this in your configuration, you will need to
  41 recheck it.
  42
  43 ## From 2.3 to 2.4 ##
  44
  45 Add the following variables to the /etc/debbugs/config file:
  46
  47 ```perl
  48 $gWebHost = "localhost";                                # e.g. www.debian.org
  49 $gWebHostBugDir = "Bugs";                               # e.g. Bugs
  50 # For now, don't change this one manually!
  51 $gWebDomain = "$gWebHost/$gWebHostBugDir";
  52 $gCGIDomain = "$gWebDomain/Bugs/cgi";                   # e.g. cgi.debian.org
  53 $gPackagePages = "packages.debian.org";                 # e.g. packages.debian.org
  54 $gSubscriptionDomain = "packages.something";            # e.g. packages.qa.debian.org
  55 $gMaintainerFileOverride = "$gConfigDir/Maintainers.override";
  56 $gUnknownMaintainerEmail = "$gMaintainerEmail";
  57 $gPackageSource = "$gConfigDir/indices/sources";
  58 ```
  59
  60 `$gWebDomain` will probably exist already; change it as shown above.
  61
  62 `$gSubscriptionDomain` is optional.
  63
  64 `$gMaintainerFileOverride is the name of a file used to manually override the
  65 Maintainers file (which is often automatically generated).
  66
  67 `$gUnknownMaintainerEmail` is the address to mail when a bug report arrives
  68 for a package with no maintainer in `$gMaintainerFile` or
  69 `$gMaintainerFileOverride`.
  70
  71 `$gPackageSource` is a file containing three tab-separated columns: package
  72 name, component (e.g. main, contrib, non-free), and the corresponding source
  73 package name.
  74
  75 Add the following variable to the `/etc/debbugs/text` file:
  76
  77 ```
  78 ############################################################################
  79 # Description of the tags
  80 ############################################################################
  81 `$gHTMLTagDesc = "
  82 <dt><code>patch</code>
  83   <dd>A patch or some other easy procedure for fixing the `$gBug is included in
  84   the `$gBug logs. If there\'s a patch, but it doesn\'t resolve the `$gBug
  85   adequately or causes some other problems, this tag should not be used.
  86
  87 <dt><code>wontfix</code>
  88   <dd>This `$gBug won\'t be fixed. Possibly because this is a choice between two
  89   arbitrary ways of doing things and the maintainer and submitter prefer
  90   different ways of doing things, possibly because changing the behaviour
  91   will cause other, worse, problems for others, or possibly for other
  92   reasons.
  93
  94 <dt><code>moreinfo</code>
  95   <dd>This `$gBug can\'t be addressed until more information is provided by the
  96   submitter. The `$gBug will be closed if the submitter doesn\'t provide ore
  97   information in a reasonable (few months) timeframe. This is for `$gBugs like
  98   \"It doesn\'t work\". What doesn\'t work?
  99
 100 <dt><code>unreproducible</code>
 101   <dd>This `$gBug can\'t be reproduced on the maintainer\'s system.  Assistance
 102   from third parties is needed in diagnosing the cause of the problem.
 103
 104 <dt><code>fixed</code>
 105   <dd>This `$gBug is fixed or worked around, but there\'s still an issue that
 106   needs to be resolved. (This will eventually replace the \"fixed\" severity)
 107
 108 <dt><code>stable</code>
 109   <dd>This `$gBug affects the stable distribution in particular.  This is only
 110   intended to be used for ease in identifying release critical `$gBugs that
 111   affect the stable distribution.  It\'ll be replaced eventually with
 112   something a little more flexible, probably.
 113 ";
 114 ```
 115
 116 The bug database is now stored in a hashed directory format (db-h).  You
 117 will need to migrate your database to this new format.  The
 118 `/usr/sbin/debbugs-dbhash` program is provided to help you perform this
 119 migration.
 120
 121 ## From 2.2 to 2.3 ##
 122
 123 There are three new scripts that have to be installed in CGI and the front
 124 page (or any other search you have set up) needs to be changed to use these
 125 scripts.  They are:
 126         * bugreport.cgi
 127         * common.pl
 128         * pkgreport.cgi
 129
 130 Add the following variables to the /etc/debbugs/config file:
 131 (the /usr/share/doc/debbugs/examples/config file can be used as a
 132 reference)
 133
 134 ```perl
 135 `$gSummaryList = "summary.list";         #debian-bugs-report@lists
 136 `$gSaveOldBugs = 1;
 137 ```
 138
 139 Make sure you do not have a double ,, as shown here if you're using the
 140 default severities.  Also, 'fixed' was added to the default severities:
 141 -                                       'normal',"Normal `$gBugs",,
 142 +                                       'normal',"Normal `$gBugs",
 143 +                                                       'fixed',"NMU Fixed $gBugs",
 144
 145 These have been added to the /etc/debbugs/text file:
 146 ```
 147 +############################################################################
 148 +#  Here is a blurb to point people to ftp archive of directions.  It is
 149 +#  used by the receive script when bouncing a badly formatted email
 150 +#
 151 +# $gTextInstructions = "$gBadEmailPrefix
 152 +# $gBadEmailPrefix Instructions are available from ftp.debian.org in /debian
 153 +# $gBadEmailPrefix and at all Debian mirror sites, in the files:
 154 +# $gBadEmailPrefix  doc/bug-reporting.txt
 155 +# $gBadEmailPrefix  doc/bug-log-access.txt
 156 +# $gBadEmailPrefix  doc/bug-maint-info.txt
 157 +# $gBadEmailPrefix";
 158 +############################################################################
 159 +$gTextInstructions = "$gBadEmailPrefix";
 160 +
 161 +
 162 ```
 163
 164 `$gHTMLStart = "<BODY TEXT=#0F0F0F>";   #this is used by HTML generation to create the "uniform look"`
 165
 166 The following code was added to /etc/debbugs/text if you use the new fixed
 167 severity
 168 ```
 169         <DT><CODE>wishlist</CODE>
 170 -       <DD>for any feature request, and also for any $gBugs that are very difficult
 171 -       to fix due to major design considerations.";
 172 +       <DD>for any feature request, and also for any $gBugs that are very
 173 +       difficult to fix due to major design considerations.";
 174 +
 175 +       <DT><CODE>fixed</CODE>
 176 +       <DD>fixed in the current version in the unstable archive but the fix has
 177 +       not been fixed by the person responsible.
 178 ```
 179  In All such entries in /etc/debbugs/text, if you replace <BODY> with
 180  `$gHTMLStart`, all html pages will have the same look (as specified in
 181  `$gHTMLStart`):
 182
 183  `$gSummaryIndex = "<HTML><HEAD><TITLE>$gProject $gBug report logs - summary index</TITLE>`
 184  `$gPackageLog = "<HTML><HEAD><TITLE>$gProject $gBug report logs - index by package</TITLE>`