[%# This Source Code Form is subject to the terms of the Mozilla Public
  # License, v. 2.0. If a copy of the MPL was not distributed with this
  # file, You can obtain one at http://mozilla.org/MPL/2.0/.
  #
  # This Source Code Form is "Incompatible With Secondary Licenses", as
  # defined by the Mozilla Public License, v. 2.0.
  #%]

[% SET title = "Bugzilla 5.2 Release Notes" %]
[% INCLUDE global/header.html.tmpl
  title = title
  bodyclasses = ['narrow_page']
%]

<h1>[% title FILTER html %]</h1>

<ul class="bz_toc">
  <li><a href="#introduction">Introduction</a></li>
  <li><a href="#point">Updates since 5.0.4</a></li>
  <li><a href="#req">Minimum Requirements</a></li>
  <li><a href="#feat">New Features and Improvements</a></li>
  <li><a href="#issues">Outstanding Issues</a></li>
  <li><a href="#code_changes">Code Changes Which May Affect
    Customizations and Extensions</a></li>
  <li><a href="https://bugzilla.readthedocs.org/en/latest/installing/upgrading.html">
    Notes On Upgrading From a Previous Version</a></li>
  <li><a href="http://www.bugzilla.org/releases/">Release Notes for Previous Versions</a></li>
</ul>

<h2 id="introduction">Introduction</h2>

<p>Welcome to [% terms.Bugzilla %] 5.2! This is kind of a weird release to explain. Back in
early 2019, versions 5.0.5 and 5.0.6 were released for the 5.0.x branch,
however, these releases contained invasive database schema and code
reformatting changes that technically should not have been allowed to land on a
stable branch. Some people noticed this, and never upgraded from 5.0.4 since
5.0.5 and 5.0.6 did not contain any security fixes. To fix this situation, 5.2
is picking up where 5.0.6 left off, since 5.0.5 technically should have been
5.2. Those still on 5.0.4 can upgrade to 5.0.4.1 if they're not ready to go a
full version release yet.</p>

<p><strong>NOTE:</strong> Because of the above situation, version 5.1.x
(development release) is actually NEWER code than 5.2, and you cannot "upgrade"
to 5.2 from 5.1.x. The 5.1.x series has been retroactively renamed to
5.3.x.</p>

<p>[% terms.Bugzilla %] is making an attempt to be 100% accessible. We're not
there yet. We have made accessibilty improvements but we're quite sure that
we've missed a lot. If you find any accessibility issues such as fields missing
labels, poor contrast, or things that don't play well with screen readers,
please file a new [% terms.bug %] which blocks our
<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=bugzilla-section508">Section 508 Compliance [% terms.bug %]</a>.</p>

<p>If you're upgrading, make sure to read
  <a href="https://bugzilla.readthedocs.org/en/latest/installing/upgrading.html">
  Notes On Upgrading From a Previous Version</a>. If you are upgrading from a
  release before 4.4, make sure to read the release notes for all the
  <a href="http://www.bugzilla.org/releases/">previous versions</a> in between
  your version and this one, <strong>particularly the Upgrading section of each
  version's release notes</strong>.</p>

<h2 id="point">Updates in this 5.2.x Release</h2>

<p>Future releases on this branch will contain a list of the updates since the
last point release in this section.</p>

<p>Because of the weird way versions 5.0.5 and 5.0.6 were released, changes
from those releases are included <a href="#point504">below</a> in case you're upgrading from the
5.0.4.x branch.</p>

<h2 id="req">Minimum Requirements</h2>

<p>Any requirements that are new since 5.0 will look like
  <span class="req_new">this</span>.</p>

<ul>
  <li><a href="#req_perl">Perl</a></li>
  <li><a href="#req_mysql">For MySQL Users</a></li>
  <li><a href="#req_mariadb">For MariaDB Users</a></li>
  <li><a href="#req_pg">For PostgreSQL Users</a></li>
  <li><a href="#req_oracle">For Oracle Users</a></li>
  <li><a href="#req_sqlite">For SQLite Users</a></li>
  <li><a href="#req_modules">Required Perl Modules</a></li>
  <li><a href="#req_optional_mod">Optional Perl Modules</a></li>
  <li><a href="#req_apache">Optional Apache Modules</a></li>
</ul>

<h3 id="req_perl">Perl</h3>

<p>Perl <span class="req_new">v5.14</span></p>

[% INCLUDE db_req db='mariadb' %]

[% INCLUDE db_req db='mysql' %]

[% INCLUDE db_req db='pg' %]

[% INCLUDE db_req db='oracle' %]

[% INCLUDE db_req db='sqlite' %]

<h3 id="req_modules">Required Perl Modules</h3>

[% INCLUDE req_table reqs = REQUIRED_MODULES
                     new = ['JSON-XS', 'Email-Sender']
                     updated = ['DateTime', 'DateTime-TimeZone',
                                'Template-Toolkit', 'URI'] %]

<h3 id="req_optional_mod">Optional Perl Modules</h3>

<p>The following perl modules, if installed, enable various
  features of [% terms.Bugzilla %]:</p>

[% INCLUDE req_table reqs = OPTIONAL_MODULES
                     new  = ['Cache-Memcached','File-Copy-Recursive']
                     updated = ['Chart', 'Test-Taint']
                     include_feature = 1 %]

<h3 id="req_apache">Optional Apache Modules</h3>

<p>If you are using Apache as your webserver, [% terms.Bugzilla %] can
  take advantage of some Apache features if you have the below Apache
  modules installed and enabled.</p>

<ul>
  <li>mod_headers</li>
  <li>mod_expires</li>
  <li>mod_env</li>
</ul>

<p>On most systems (but not on Windows), <kbd>checksetup.pl</kbd> is able to
  tell whether or not you have these modules installed, and it will tell
  you.</p>


<a name="v52_feat"></a>
<h2 id="feat">New Features and Improvements</h2>

<ul>
  <li><a href="#feat_mobilerender">Improved Mobile Rendering</a></li>
  <li><a href="#feat_mariadb">Explicit MariaDB Support</a></li>
  <li><a href="#feat_mysql8">MySQL 8+ Support</a></li>
  <li><a href="#feat_utf8mb4">Better Unicode support on MySQL and MariaDB</a></li>
  <li><a href="#feat_docker">Demo Docker Configuration</a></li>
  <li><a href="#feat_other">Other Enhancements and Changes</a></li>
</ul>

<h3 id="feat_mobilerender">Improved Mobile Rendering</h3>

<p>
Metadata to assist browsers in properly rendering [% terms.Bugzilla %] on mobile browsers was added. Without this metadata Google Search tools would report [% terms.Bugzilla %] pages as not suitable for mobile devices. [% terms.Bugzilla %] still needs work to actually look nice on mobile devices but this is a good start. (<a href="https://github.com/bugzilla/bugzilla/pull/78">PR #78</a>)
</p>

<h3 id="feat_mariadb">Explicit MariaDB Support</h3>

<p>Newer versions of MariaDB (10.6 and newer) have diverged from MySQL
sufficiently that you can't really call it a drop-in replacement for MySQL
anymore. We new have a 'mariadb' database driver for all versions of MariaDB.
<code>checksetup.pl</code> will prompt you to switch to it if it detects that you are connected to a MariaDB database server.
[%+ INCLUDE buglink id=1467006 %]</p> 

<h3 id="feat_mysql8">MySQL 8+ Support</h3>

<p>Bugzilla previously did not work on MySQL 8 or newer. Now it does.
[%+ INCLUDE buglink id=1592129 %]</p>

<h3 if="feat_utf8mb4">Better Unicode support on MySQL and MariaDB</h3>

<p>The <b>utf8mb4</b> character set is now used by default on new installs making use of either MariaDB or MySQL. This should resolve many issues related to character encoding found in older versions.
[%+ INCLUDE buglink id=1891882 %]</p>

<h3 id="feat_docker">Demo Docker Configuration</h3>

<p>[% terms.Bugzilla %] now ships with a Docker Compose configuration which
provides an out-of-the-box [% terms.Bugzilla %] with a default configuration to
test with. Type <code>docker compose up</code> in the root [% terms.bugzilla %]
directory to start it up. You will be prompted on the console with how to
connect to it once it comes up. Requires that you have Docker already
installed. This configuration is not suitable for production use, and is just
for playing around with it and testing it without needing to do a full
installation.
[%+ INCLUDE buglink id=1888068 %]</p>

<h3 id="feat_other">Other Enhancements and Changes</h3>

<h4>Enhancements for Users</h4>

<ul>
  <li><strong>UI:</strong> WineHQ Forum links are now accepted in the See Also field on [% terms.bugs %]. [% INCLUDE buglink id=1523814 %]</li>
  <li><strong>Accessibility:</strong> Color contrast in the default theme was adjusted to comply with WCAG AA 2.0 recommendations. [% INCLUDE buglink id=1798166 %]</li>
  <li><strong>Email:</strong> Emails about [% terms.bugs %] now include an <code>X-Bugzilla-ID</code> header which lists the [% terms.Bug %] ID, for potential use in filtering. [% INCLUDE buglink id=1403169 %]</li>
</ul>

<h4>Enhancements for Administrators and Developers</h4>

<ul>
  <li><strong>Database:</strong> <strong>UTF8 data encoding is now
    enforced.</strong> Older version of [% terms.Bugzilla %] made the
    conversion of older data to UTF8 optional. Converting your existing data to
    UTF8 is now mandatory. Your data will be converted when you run
    <kbd>checksetup.pl</kbd>. If you are not already encoding your data in UTF8
    you may want to verify that it will correctly convert on a backup copy of
    your database before upgrading.</li>
  <li><strong>Database:</strong>If you are using MySQL, the majority of the
    database tables will also be converted to the InnoDB storage engine. This
    makes searching more efficent and allows for real referential
    integrity.</li>
  <li><strong>Installation:</strong> [% terms.Bugzilla %] now supports
    Email::MIME version 1.949 and newer, which previously would crash
    [%+ terms.Bugzilla %] when it tried to send email.
    [%+ INCLUDE buglink id=1657496 %]</li>
  <li><strong>Installation:</strong> The <code>testserver.pl</code> script will
    now work with self-signed SSL certificates if you pass the
    <code>--self-signed</code> option on the command line. [% INCLUDE buglink id=1851398 %]</li>
  <li><strong>Installation:</strong> An foreign key error when upgrading from
    versions prior to 3.0 to 5.0.6 or newer was fixed. [% INCLUDE buglink id=1902375 %]</li>
</ul>

<h4 id="feat_webservices_other">WebService Changes</h4>

<ul>
  <li><strong>Group.get</strong> method is now properly marked as Read Only. [% INCLUDE buglink id=1584477 %]</li>
</ul>

<h4 id="code_changes">Code Changes Which May Affect Customizations and Extensions</h4>

<ul>
  <li>The Bugzilla::DB object now has a qi attribute which returns a special
    hashref that can be used inside double-quoted strings to quote database
    identifiers.<br>
    <code>
  my $q = Bugzilla-&gt;dbh-&gt;qi;
  Bugzilla-&gt;dbh-&gt;do("SELECT COUNT(*) FROM $q-&gt;{groups}");
    </code><br>
    [% INCLUDE buglink id=1592129 %]
  </li>
  <li>[% terms.Bugzilla %] now uses Email::Address::XS instead of Email::Address for managing email address parsing. If you made use of Email::Address directly you should update to use Email::Address::XS instead. [% INCLUDE buglink id=1853138 %]</li>
</ul>

<h3 id="point504">Changes since Version 5.0.4</h3>

<p>Because of the weird way we branched to fix the 5.0.5 numbering problem, the
changes from 5.0.5 and 5.0.6 are included here in case you're upgrading from
the 5.0.4.x branch.</p>

<h3>5.0.6</h3>

<ul>
<li><strong>Adminstration:</strong> It is now possible to create more than 255
flags (up to 65535) [% INCLUDE buglink id=1526703 %]</li>
</ul>

<h3>5.0.5</h3>

<ul>
<li><strong>User Interface:</strong> Email addresses with apostrophes (yes,
that's legal) no longer break the "Send Mail to [% terms.Bug %] Assignees"
button on [% terms.bug %] lists. [% INCLUDE buglink id=1226123 %]</li>
<li><strong>Installation/Upgrading:</strong> If using MySQL, the
<code>bugs_fulltext</code> table is now InnoDB instead of MyISAM. This may
cause your upgrade to take a while. [% INCLUDE buglink id=981487 %]</li>
<li><strong>Developers:</strong> This release reformats the code according to
the same conventions as the popular Mojolicious product and includes a
<code>.perltidyrc</code> to do the same.  You may use whatever coding style you
want, but all files commited to the repo must be reformatted according to those
rules.</li>
<li><strong>Developers:</strong> A new hook <code>template_after_create</code>
was added, which can be used to manipulate the template object before it gets
rendered. You can use this to define new Template Toolkit virtual methods or
filters in extensions.
(<a href="https://github.com/bugzilla/bugzilla/pull/60">PR #60</a>)</li>
</ul>

<ul>[% INCLUDE global/footer.html.tmpl %]

[% BLOCK buglink %]
(<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=[%- id FILTER html -%]">[% terms.Bug %] [%+ id FILTER html -%]</a>)
[% END %]

[% BLOCK db_req %]
  [% SET m = DB_MODULE.$db %]
  <h3 id="req_[% db FILTER html %]">For [% m.name FILTER html %] Users</h3>

  <ul>
    <li>[% m.name FILTER html %]
       [%+ '<span class="req_new">' IF db_new %]v[% m.db_version FILTER html %]
       [% '</span>' IF db_new %]
       </li>
    [% IF m.db_blklst_str %]
    <li><strong>but not versions:</strong> [% m.db_blklst_str FILTER html %]</li>
    [% END %]
    <li><strong>perl module:</strong>
      [%+ m.dbd.module FILTER html %]
      [%+ '<span class="req_new">' IF dbd_new %]
        [% SWITCH m.dbd.version -%]
        [%   CASE '' %]any version
        [%   CASE DEFAULT %]v[% m.dbd.version FILTER html %]
        [% END %]
      [% '</span>' IF dbd_new %]</li>
  </ul>
[% END %]


[% BLOCK req_table %]
  <table class="req_table">
    <tr>
      <th>Module</th> <th>Version</th>
      [% IF include_feature %]
        <th>Enables Feature</th>
      [% END %]
    </tr>
    [% FOREACH req = reqs %]
      <tr>
        <td [% ' class="req_new"' IF new.contains(req.package) %]>
          [%- req.module FILTER html %]</td>
        <td [% ' class="req_new"' IF updated.contains(req.package)
                                     OR new.contains(req.package) %]>
          [%- IF req.version == 0 %]
            (Any)
          [% ELSE %]
            [%- req.version FILTER html %]
          [% END %]
        </td>
        [% IF include_feature %]
          <td>[% req.feature.join(', ') FILTER html %]</td>
        [% END %]
      </tr>
    [% END %]
</table>
[% END %]
