Bug 286274: Release Notes for 2.20

Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=colin

1 files changed, 563 insertions, 1 deletions

diff --git a/docs/rel_notes.txt b/docs/rel_notes.txt
index d78389aeb..120ee819d 100644
--- a/docs/rel_notes.txt
+++ b/docs/rel_notes.txt
@@ -1,5 +1,567 @@
+***************************************
+*** The Bugzilla 2.20 Release Notes ***
+***************************************
+
+Table of Contents
+*****************
+
+- Introduction
+- Minimum Requirements
+    * Perl
+    * For MySQL Users
+    * For PostgreSQL Users
+    * Required Perl Modules
+    * Optional Perl Modules
+- What's New?
+    * Experimental PostgreSQL Support
+    * New User-Interface Color/Style
+    * Higher-Level Categorization of Bugs (above "Product")
+    * Regular Reports by Email of Complex Queries ("Whining")
+    * "Environment Variable" Authentication Method
+    * User-List Drop-Down Menus
+    * Server-Side Comment Wrapping
+    * UI for Editing Priority, OS, Platform, and Severity
+    * Bugzilla Queries as RSS
+    * Choice of E-Mail Sending Methods
+    * "User Preferences"
+    * "Large Attachment" Storage
+    * Miscellaneous Improvements
+    * All Changes
+- Deprecated Features
+- Outstanding Issues (<======================== IMPORTANT, PLEASE READ)
+- How to Upgrade From An Older Bugzilla
+    * Steps for Upgrading
+- Code Changes Which May Affect Customizations
+    * The New Database-Compatibility Layer
+    * If You Customize Your Database...
+    * Many Functions Renamed
+    * User Preferences
+    * Other Changes
+- Security Fixes In 2.20 Releases
+- Release Notes for Previous Versions
+
+
+Introduction
+************
+
+This document contains the release notes for Bugzilla 2.20.
+In this document, recently added, changed, and removed features
+of Bugzilla are described. If you are upgrading from an older version,
+you will definitely want to read these release notes in detail, so that
+you have an idea of what has changed.
+
+If you are upgrading from a version before 2.18, also read the 2.18 release
+notes (lower in this file) and any previous release notes.
+
+If you are installing a new Bugzilla, you will still want to look over
+the release notes to see if there is any particularly important information
+that affects your installation.
+
+The 2.20 release is our current stable series. It has had about nine 
+months of development since 2.18, but they were nearly the most active
+nine months in Bugzilla's history. We hope that users will appreciate 
+our many external changes, and that Bugzilla administators will find 
+that our internal changes make their lives easier.
+
+If you would like to contribute code to Bugzilla, read our 
+Contributor's Guide at:
+
+http://www.bugzilla.org/docs/contributor.html
+
+
+Minimum Requirements
+********************
+
+Perl
+----
+
+  Perl v5.6.1            (changed from 2.18)  (Non-Windows platforms)
+  ActiveState Perl v5.8.1                     (Windows only)
+
+For MySQL Users
+---------------
+
+  MySQL v3.23.41                   (Note: 2.22 will require MySQL 4.x)
+  perl module: DBD::mysql v2.9003  (changed from 2.18)
+
+For PostgreSQL Users       (new in 2.20)
+--------------------
+
+  PostgreSQL 7.3.x         (8.x has not been tested, but may work)
+  perl module: DBD::Pg 1.31
+
+Required Perl Modules
+---------------------
+
+  AppConfig v1.52
+  CGI v2.93
+  Data::Dumper (any)
+  Date::Format v2.21
+  DBI v1.38              (changed from 2.18)
+  File::Spec v0.82
+  File::Temp (any)
+  Template Toolkit v2.08
+  Text::Wrap v2001.0131
+  Mail::Mailer 1.65      (new in 2.20)
+  Storable (any)         (new in 2.20)
+
+Optional Perl Modules
+---------------------
+
+  Chart::Base v1.0
+  GD v1.20
+  GD::Graph (any)
+  GD::Text::Align (any)
+  Net::LDAP (any)
+  PatchReader v0.9.4
+  XML::Parser (any)
+
+
+What's New?
+***********
+
+Experimental PostgreSQL Support
+-------------------------------
+
+In addition to MySQL, Bugzilla now also supports PostgreSQL. PostgreSQL
+support is still somewhat experimental. Although most major features of
+Bugzilla work on PostgreSQL in 2.20, there are probably still a few bugs
+that need to be worked out.
+
+PostgreSQL support in 2.20 is acceptable for smaller production
+environments that don't mind running into a bug or two now and then.
+
+
+New User-Interface Color/Style
+------------------------------
+
+You'll notice that Bugzilla looks a bit nicer, now! We've made a few
+color and style changes to update the overall "feel" of Bugzilla's
+User Inteface. We plan to do even more work on the UI for 2.22.
+
+
+Higher-Level Categorization of Bugs (above "Product")
+-----------------------------------------------------
+
+Previous Bugzillas had "Products" that you could file bugs in,
+and "Components" for those products. Now, "Products" can be grouped
+into "Classifications."
+
+To enable this, a Bugzilla administrator can turn on the 
+"useclassification" parameter, using editparams.cgi.
+
+
+Regular Reports by Email of Complex Queries ("Whining")
+-------------------------------------------------------
+
+You can now tell Bugzilla to do a specific query (or set of queries)
+every X minutes/hours/days, and send you the results by email. This is
+great for keeping track on a daily basis of what's going on in 
+your Bugzilla.
+
+
+"Environment Variable" Authentication Method
+--------------------------------------------
+
+You can now tell Bugzilla to accept a certain value passed in from
+Apache as authentication for Bugzilla users. This means that Bugzilla
+now "supports" any type of authentication that Apache supports.
+
+To use this, FIXME ----- EXPLAIN THIS BEFORE 2.20 RELEASE ----- FIXME
+
+
+User-List Drop-Down Menus
+-------------------------
+
+Now, anywhere in Bugzilla where you previously had to type in an
+email address by hand, you have the choice of having Bugzilla instead
+display a drop-down menu of users to pick from.
+
+This feature is best for small installations with few users, because
+on large installations the list grows too large to be useful.
+
+To enable the feature, turn on the "usemenuforusers" parameter in
+editparams.cgi.
+
+
+Server-Side Comment Wrapping
+----------------------------
+
+In older Bugzillas, comments were wrapped to 80 characters by the
+user's web browser, and then stored in the database that way. This caused
+problems because some browsers did not wrap comments properly.
+
+Now, Bugzilla stores comments unwrapped and wraps them at display time, so
+all new comments should be properly wrapped. Also, when you upgrade, Bugzilla
+will look for old "mis-wrapped" comments and attempt to wrap them properly.
+
+Lines beginning with the ">" character are assumed to be quotes, and are
+*not* wrapped.
+
+
+UI for Editing Priority, OS, Platform, and Severity
+---------------------------------------------------
+
+Bugzilla now has a User Interface for adding and removing values
+from the OS, Platform, Priority, and Severity fields. You can also
+rename values. Any user in the "editcomponents" group can click
+on the "Field Values" link in their page footer to edit these fields.
+
+Also, the default list of choices for OS and Platform for new 
+installations is now much smaller. Old installations will keep 
+the same list they have now.
+
+
+Bugzilla Queries as RSS
+-----------------------
+
+You can now view a Bugzilla query as valid RSS 1.0. This means that you
+could add a particular query to your RSS aggregator, if you wanted, to
+keep track of changes in Bugzilla.
+
+To see a query as RSS, just click on the "RSS" link on the bottom of
+your query results. Your query must return at least 1 result in order
+for you to see the link.
+
+
+Choice of E-Mail Sending Methods
+--------------------------------
+
+Bugzilla now uses perl's Mail::Mailer to send e-mail. This means that
+you have several choices of how Bugzilla can send email. By default, it
+still uses sendmail, but it can also use SMTP, qmail, or send all email
+to a file instead of out to users.
+
+A Bugzilla administrator can change which method is used by setting the
+"mail_delivery_method" parameter in editparams.cgi.
+
+
+"User Preferences"
+------------------
+
+Bugzilla users will now notice a section in their Preferences called
+"General Preferences." Administrators will notice a new link called
+"User Preferences."
+
+The Preferences system allows Bugzilla developers to specify arbitrary
+"user preferences" that change the behavior of certain parts of Bugzilla.
+Administrators can control whether or not users are allowed to use these
+preferences, and what the default settings are for a user who is not
+logged in.
+
+The first two preferences that we have implemented are:
+  + "Show a quip at the top of each bug list"
+  + "When viewing a bug, show comments in this order..."
+
+We plan to implement more preferences in the future.
+
+
+"Large Attachment" Storage
+--------------------------
+
+Bugzilla can now store very large attachments on disk instead of in the
+database. These attachments can't be searched with Boolean Charts, but
+they also don't take up database space, and they can be deleted individually
+by the admin.
+
+When uploading an attachment, a user chooses if it's a "Big File." If so,
+it's stored on the disk instead of in the database.
+
+To enable this feature, set the "maxlocalattachmentsize" parameter to
+a non-zero value, in editparams.cgi.
+
+
+Miscellaneous Improvements
+--------------------------
+
+- Marking an attachment as obsolete will now cancel all pending flag
+  requests for that attachment. That is, any flag that was set to "?"
+  on that attachment will be cleared.
+
+- You can now see which users are "watching" you, on the email 
+  preferences page.
+
+- You can tell Bugzilla to mark certain comments in a different
+  color by adding "&mark=1,2,3,5-7" to the end of the show_bug.cgi URL,
+  where "1,2,3,5-7" means "highlight comment 1, comment 2, comment 3, and
+  comments 5 through 7."
+
+- "QA Contact" now also appears on the New Bug page, if QA Contacts are
+  enabled on your installation.
+
+- Bugzilla email now has the "In-Reply-To" header added to it, so if
+  you use an email client that supports threads, you can view your
+  Bugzilla email in threads. If you are upgrading to a new version of
+  Bugzilla, and you want this support, please see the instructions at:
+  https://bugzilla.mozilla.org/attachment.cgi?id=172267
+
+- The email preferences system has been slightly updated. You will notice
+  the changes on your Email Preferences page.
+
+- You can now negate individual "boolean charts" (in the 
+  "Advanced Searching" section at the bottom of the "Advanced 
+   Search" page). That is, you can add "NOT" to the front of them.
+
+- You can add the words %assignee%, %reporter%, %user% (yourself), or
+  %qacontact% on the right-hand side of a Boolean Chart. For example, you
+  could make a Boolean Chart which said "Reporter" "does not equal" 
+  "%assignee%". That would give you all bugs where the Reporter was not
+  the same as the Assignee.
+
+- You can now search Boolean Charts by "commenter."
+
+- If you have a group with no name, it will be re-named to "group_#" where
+  "#" is the numeric Bugzilla Group ID for that group.
+
+- If you are using time-tracking, you can now see a report of time spent
+  on bugs using summarize_time.cgi.
+
+- If you are using time-tracking, bugzilla will now set "hours remaining"
+  to "0" automatically if you RESOLVE a bug, whether you are in the
+  time-tracking group or not.
+
+
+Deprecated Features
+*******************
+
+- Bugzilla 2.20 is the last Bugzilla version to support MySQL 3.23.x.
+  Starting with Bugzilla 2.22, Bugzilla will require MySQL 4.0.x. This will
+  allow Bugzilla to take advantage of the advanced features of MySQL 4.
+
+
+Outstanding Issues
+******************
+
+- (No Bug Number) VERY IMPORTANT: If you have customized the values in
+  your Status/Resolution field, you must edit checksetup.pl BEFORE YOU
+  RUN IT. Find the line that starts like this:
+
+  my @states = ("UNCONFIRMED",
+
+  That's where you set the values for the Status field.
+
+  my @resolutions = ("","FIXED",
+
+  And that's where you set values for the Resolution field.
+
+  Those are both near line 1786 in checksetup.pl.
+
+  If you forget to do this, you will have to manually edit the "bug_status"
+  and "resolution" tables in the database to contain the correct values.
+
+- bug 37765: VERY IMPORTANT: If you use the "sendmail" support of Bugzilla,
+  and you use an MTA which is *not* Sendmail (such as Postfix, Exim, etc.) 
+  you MUST turn on the "sendmailnow" parameter or Bugzilla will not send 
+  e-mail correctly.
+
+- (No Bug Number) If you close your web browser while the process_bug.cgi
+  or post_bug.cgi screen is running, not all emails will be sent, and
+  the next time that that bug is updated, there will be two updates. This
+  is because of a behavior of Apache that is beyond our control.
+
+- bug 276230: The support for restricting access to particular Categories of 
+  New Charts is not complete. You should treat the 'chartgroup' Param as the 
+  only access mechanism available. However, additionally, charts migrated from
+  Old Charts will be restricted to the groups that are marked MANDATORY for 
+  the corresponding Product. There is currently no way to change this 
+  restriction, and the groupings will not be updated if the group configuration
+  for the Product changes.
+
+- bug 69621: If you rename or remove a keyword that is in use on bugs, you will
+  need to rebuild the "keyword cache" by running sanitycheck.cgi and choosing
+  the option to rebuild the cache when it asks. Otherwise keywords may not show
+  up properly in search results.
+
+- (No Bug Number) If you have a lot of non-ASCII data in your Bugzilla (for 
+  example, if you use a translation of Bugzilla), don't enable the XS::Stash
+  option when you install the Template Toolkit, or your Bugzilla installation
+  may become slow. This problem is fixed in a not-yet-released version of the
+  Template Toolkit (after 2.14).
+
+- If at any time you upgraded from a version of Bugzilla between 2.17.4 -
+  2.17.7 to either 2.18rc3 or 2.19.1, you must manually fix your New Charts in
+  order for them to work. See the following link for instructions on how to do
+  this: https://bugzilla.mozilla.org/show_bug.cgi?id=276237#c18
+  If you are using 2.18rc3, but did not upgrade from version 2.17.4 or newer,
+  then you don't need to do this.
+
+- (No Bug Number) If your DBI is really, really old, Bugzilla might fail
+  with a strange error message when you try to run checksetup.pl. Try
+  upgrading your DBI using: perl -MCPAN -e'install DBI'
+
+- Bug 298659: LDAP support may be broken on Windows.
+
+- Bug 126266: Bugzilla does not use UTF-8 to display pages. This means
+  that if you enter non-ASCII characters into Bugzilla, they may
+  display strangely, or Bugzilla may have other problems. For a workaround,
+  see: http://www.bugzilla.org/docs/tip/html/security-bugzilla.html
+
+- Bug 99215: Flags are not protected by "mid-air collision" detection.
+  Nor are any attachment changes.
+
+- Bug 89822: When changing multiple bugs at the same time, there is no
+  "mid-air collision" protection.
+
+- Bug 285614: importxml.pl may be broken in many different ways.
+
+
+Upgrading From An Older Bugzilla
+************************************
+
+NOTE: Running checksetup.pl to upgrade a large installation (over 10,000 bugs)
+      may take a significant amount of time. checksetup will try to let
+      you know how long it will take, but expect downtime of an hour or
+      more if you have many bugs, many attachments, or many users.
+
+Steps for Upgrading
+-------------------
+
+1) View the Sanity Check (sanitycheck.cgi) page on your installation before
+   upgrading. Attempt to fix all warnings that the page produces before
+   you go any further, or you may experience problems during your upgrade.
+
+2) Make a backup of the  Bugzilla database before you upgrade, perhaps 
+   by using mysqldump.
+
+   Example:
+
+      mysqldump -u root -p --databases bugs > bugs.db.backup
+
+3) Replace the files in your installation with the new version of Bugzilla,
+   or you can try to use CVS to upgrade. The Bugzilla.org website has 
+   instructions on how to do the actual installation.
+
+4) Make sure that you run checksetup.pl after you install the new version.
+
+5) View the Sanity Check page again after you run checksetup.pl.
+
+6) It is recommended that, if possible, you fix any problems you find
+   immediately. Failure to do this may mean that Bugzilla will not work 
+   correctly. Be aware that if the sanity check page contains more errors after
+   an upgrade, it doesn't necessarily mean there are more errors in your 
+   database, as additional tests are added to the sanity check over time, and 
+   it is possible that those errors weren't being checked for in the old 
+   version.
+
+7) If you want threading support on your Bugzilla email (see the 
+   "Miscellaneous Improvements" section above for a description),
+    you need to follow the instructions at:
+    https://bugzilla.mozilla.org/attachment.cgi?id=172267
+
+
+Code Changes Which May Affect Customizations
+********************************************
+
+The New Database-Compatibility Layer
+------------------------------------
+
+For most customizations, this should have no effect. However, you should
+be aware that Bugzilla->dbh is now an instance of "Bugzilla::DB" instead
+of being a DBI object directly. In fact, it's actually a 
+Bugzilla::DB::Mysql for MySQL users, and a Bugzilla::DB::Pg for 
+PostgreSQL users.
+
+Anything called from $dbh (like $dbh->bz_last_key) that starts with
+"bz_" or "sql_" is a custom Bugzilla function. Anything *not* starting
+with those two prefixes is a normal DBI function.
+
+Methods whose names start with "sql_" generate a piece of a SQL statement.
+They generate the correct version of the statement for whichever database
+you are using.
+
+Methods whose names start with "bz_" do something directly.
+
+You can see more documentation about this at:
+
+http://www.bugzilla.org/docs/2.20/pod/Bugzilla/DB.pm
+
+
+If You Customize Your Database...
+---------------------------------
+
+In order to support multiple databases, we had to do something sort of
+tricky. Bugzilla now stores what it *thinks* the current database schema
+is, in a table called bz_schema.
+
+This means that when checksetup changes the database, it updates the
+bz_schema table. When *you* update the database, without using 
+checksetup to do it, the bz_schema table is *not* updated.
+
+So, if you're going to add/remove a new column/table to Bugzilla, or if you're
+going to change the definition of a column, try to do it by adding code to
+checksetup in the correct place. (It's one of the places where you find
+the word "--TABLE--".)
+
+You can see the documentation on the $dbh functions used to do this at:
+
+http://www.bugzilla.org/docs/2.20/pod/Bugzilla/DB.pm#schema_modification_methods
+
+
+Many Functions Renamed
+----------------------
+
+We are reorganizing the Bugzilla code so that it can support mod_perl. As
+part of this, we are moving all functions out of globals.pl and CGI.pl, and
+into modules in the Bugzilla/ directory.
+
+Sometimes when we moved them, we also renamed them. The new Bugzilla standard
+is to have functions_named_like_this, instead of FunctionsNamedLikeThis.
+
+So if you were using a FunctionNamedLikeThis that no longer works, try just
+using it as function_named_like_this. If that doesn't work, you may have to
+search for where we put it, and what we renamed it to. Most of the functions
+moved to logical places.
+
+If you really can't find it, search bugzilla.mozilla.org using the name
+of the old function. We usually moved one function per bug, so the new
+name will be somewhere in a bug report.
+
+
+User Preferences
+----------------
+
+Bugzilla now has a "User Preferences" system! These preferences are stored
+in the database, and specified by a Bugzilla developer. The Bugzilla
+developers actually call these "settings," but we called them "User 
+Preferences" in the UI to make things clearer.
+
+You access a user's settings differently depending on if you are in a
+.cgi file or in a template file:
+
+CGI: Bugzilla->user->settings->{'setting_name'}->value
+Template: Bugzilla.user.settings.setting_name.value
+
+Where "setting_name" is the name of the setting. You can see the current
+setting names in the "setting" table in the database.
+
+Remember that sometimes you may want to check a user's settings when 
+making a customization.
+
+To see how to add new settings, search for "add_setting" in checksetup.pl.
+Also see the template: template/en/default/global/setting-descs.none.tmpl.
+
+Other Changes
+-------------
+
+- The $::unconfirmedstate variable has been replaced by the actual string
+  "UNCONFIRMED" everywhere in Bugzilla code.
+
+- The %::FORM and %::MFORM variables are no longer used to access form
+  data. Instead, use $cgi->param(). There are many examples of how to do
+  this, all over the Bugzilla code.
+
+- SendSQL() and related calls are deprecated, and the various $dbh methods
+  should be used instead, such as $dbh->prepare() and $dbh->execute().
+  Bugzilla->dbh is the $dbh handle to use. We expect SendSQL to completely
+  disappear by 2.22. For more information on how to use the $dbh methods, 
+  see:  http://search.cpan.org/dist/DBI/DBI.pm
+
+
+Release Notes for Previous Versions
+***********************************
+
 *****************************************
-*** The Bugzilla 2.18.2 Release Notes ***
+*** The Bugzilla 2.18.x Release Notes ***
 *****************************************
 
 Table of Contents