From: Gervase Markham Date: Fri, 19 Sep 2014 13:34:50 +0000 (+0100) Subject: WIP X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b61851e9192e57b6e996cb9ca54f06ea9aa2ffbe;p=thirdparty%2Fbugzilla.git WIP --- diff --git a/docs/en/rst/about.rst b/docs/en/rst/about/index.rst similarity index 100% rename from docs/en/rst/about.rst rename to docs/en/rst/about/index.rst diff --git a/docs/en/rst/administering.rst b/docs/en/rst/administering.rst deleted file mode 100644 index f772060dca..0000000000 --- a/docs/en/rst/administering.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _administering: - -====================== -Administering Bugzilla -====================== - -For those with :group:`admin` privileges, Bugzilla can be administered using -the :guilabel:`Administration` link in the header. The administrative -controls are divided into several sections: - -.. toctree:: - :maxdepth: 2 - - administering/parameters - administering/preferences - administering/users - administering/categorization - administering/flags - administering/custom-fields - administering/field-values - administering/workflow - administering/groups - administering/keywords - administering/whining - administering/quips - administering/extensions diff --git a/docs/en/rst/administering/index.rst b/docs/en/rst/administering/index.rst new file mode 100644 index 0000000000..5f8b3ccc0b --- /dev/null +++ b/docs/en/rst/administering/index.rst @@ -0,0 +1,26 @@ +.. _administering: + +====================== +Administering Bugzilla +====================== + +For those with :group:`admin` privileges, Bugzilla can be administered using +the :guilabel:`Administration` link in the header. The administrative +controls are divided into several sections: + +.. toctree:: + :maxdepth: 2 + + parameters + preferences + users + categorization + flags + custom-fields + field-values + workflow + groups + keywords + whining + quips + extensions diff --git a/docs/en/rst/conf.py b/docs/en/rst/conf.py index 6a0349b95e..2f0c722ffd 100644 --- a/docs/en/rst/conf.py +++ b/docs/en/rst/conf.py @@ -78,7 +78,7 @@ for line in open("../../../Bugzilla/Constants.pm"): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +exclude_patterns = ['*.inc.rst'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None diff --git a/docs/en/rst/customizing.rst b/docs/en/rst/customizing.rst deleted file mode 100644 index 9f7887ca27..0000000000 --- a/docs/en/rst/customizing.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. highlight:: perl - -.. _customizing: - -==================== -Customizing Bugzilla -==================== - -.. toctree:: - :maxdepth: 2 - - customizing/existing-parameters - customizing/extensions - customizing/skins - customizing/languages - customizing/templates - customizing/who-can-change-what - customizing/writing-extensions diff --git a/docs/en/rst/customizing/index.rst b/docs/en/rst/customizing/index.rst new file mode 100644 index 0000000000..71b08b5ee1 --- /dev/null +++ b/docs/en/rst/customizing/index.rst @@ -0,0 +1,18 @@ +.. highlight:: perl + +.. _customizing: + +==================== +Customizing Bugzilla +==================== + +.. toctree:: + :maxdepth: 2 + + existing-parameters + extensions + skins + languages + templates + who-can-change-what + writing-extensions diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst index 07506bf87e..386cefc4ef 100644 --- a/docs/en/rst/index.rst +++ b/docs/en/rst/index.rst @@ -6,11 +6,11 @@ Bugzilla Documentation :maxdepth: 2 :numbered: - about - installing - upgrading - maintaining - customizing - integrating - administering - using + about/index + installing/index + upgrading/index + maintaining/index + customizing/index + integrating/index + administering/index + using/index diff --git a/docs/en/rst/installing.rst b/docs/en/rst/installing/index.rst similarity index 82% rename from docs/en/rst/installing.rst rename to docs/en/rst/installing/index.rst index 97e56d9ef2..608185b70f 100644 --- a/docs/en/rst/installing.rst +++ b/docs/en/rst/installing/index.rst @@ -21,10 +21,10 @@ case, you may want to read the :ref:`Quick Start instructions `. .. toctree:: :maxdepth: 2 - installing/quick-start - installing/linux - installing/windows - installing/mac-os-x - installing/post-install-config - installing/migrating - installing/moving + quick-start + linux + windows + mac-os-x + post-install-config + migrating + moving diff --git a/docs/en/rst/integrating.rst b/docs/en/rst/integrating/index.rst similarity index 76% rename from docs/en/rst/integrating.rst rename to docs/en/rst/integrating/index.rst index 6c4cb2e72b..ad1f412c9e 100644 --- a/docs/en/rst/integrating.rst +++ b/docs/en/rst/integrating/index.rst @@ -7,6 +7,6 @@ Integrating with Bugzilla .. toctree:: :maxdepth: 2 - integrating/apis - integrating/tips + apis + tips diff --git a/docs/en/rst/maintaining/backups.rst b/docs/en/rst/maintaining/backups.rst index bef3c3ada4..384c79437b 100644 --- a/docs/en/rst/maintaining/backups.rst +++ b/docs/en/rst/maintaining/backups.rst @@ -31,9 +31,8 @@ PostgreSQL Bugzilla ======== -It's also a good idea to back up the Bugzilla directory itself, as there are -some data files and configuration files stored there which you would want to -retain. A simple recursive copy will do the job here. +The Bugzilla directory contains some data files and configuration files which +you would want to retain. A simple recursive copy will do the job here. :command:`cp -rp $BUGZILLA_HOME /var/backups/bugzilla` diff --git a/docs/en/rst/maintaining.rst b/docs/en/rst/maintaining/index.rst similarity index 51% rename from docs/en/rst/maintaining.rst rename to docs/en/rst/maintaining/index.rst index 299f011be8..e92c8c5552 100644 --- a/docs/en/rst/maintaining.rst +++ b/docs/en/rst/maintaining/index.rst @@ -7,7 +7,7 @@ Maintaining Bugzilla .. toctree:: :maxdepth: 2 - maintaining/upgrades - maintaining/backups - maintaining/sanity-check - maintaining/merging-accounts + upgrades + backups + sanity-check + merging-accounts diff --git a/docs/en/rst/maintaining/upgrades.rst b/docs/en/rst/maintaining/upgrades.rst index e02a536f31..99af808f7d 100644 --- a/docs/en/rst/maintaining/upgrades.rst +++ b/docs/en/rst/maintaining/upgrades.rst @@ -6,8 +6,9 @@ Upgrades For details on how to upgrade Bugzilla, see the :ref:`upgrading` chapter. Bugzilla can automatically notify administrators when new releases are -available if the :guilabel:`upgrade_notification` parameter is set. Administrators -will see these notifications when they access the Bugzilla home page. Bugzilla -will check once per day for new releases. If you are behind a proxy, you may -have to set the :guilabel:`proxy_url` parameter accordingly. If the proxy -requires authentication, use the ``http://user:pass@proxy_url/`` syntax. +available if the :param:`upgrade_notification` parameter is set. +Administrators will see these notifications when they access the Bugzilla home +page. Bugzilla will check once per day for new releases. If you are behind a +proxy, you may have to set the :param:`proxy_url` parameter accordingly. If +the proxy requires authentication, use the +:paramval:`http://user:pass@proxy_url/` syntax. diff --git a/docs/en/rst/upgrading.rst b/docs/en/rst/upgrading.rst deleted file mode 100644 index b2a32d1473..0000000000 --- a/docs/en/rst/upgrading.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _upgrading: - -================== -Upgrading Bugzilla -================== - -.. toctree:: - :maxdepth: 2 - - upgrading/overview - upgrading/upgrading-with-git - upgrading/upgrading-from-bazaar - upgrading/upgrading-from-cvs - upgrading/upgrading-with-a-tarball diff --git a/docs/en/rst/upgrading/index.rst b/docs/en/rst/upgrading/index.rst new file mode 100644 index 0000000000..937fdaeea3 --- /dev/null +++ b/docs/en/rst/upgrading/index.rst @@ -0,0 +1,15 @@ +.. _upgrading: + +================== +Upgrading Bugzilla +================== + +.. toctree:: + :maxdepth: 2 + + overview + upgrading-with-git + migrating-from-bzr + migrating-from-cvs + migrating-from-a-tarball + upgrading-with-a-tarball diff --git a/docs/en/rst/upgrading/upgrading-from-1.rst.inc b/docs/en/rst/upgrading/migrating-from-1.rst.inc similarity index 64% rename from docs/en/rst/upgrading/upgrading-from-1.rst.inc rename to docs/en/rst/upgrading/migrating-from-1.rst.inc index a53d050d74..481d1b2afc 100644 --- a/docs/en/rst/upgrading/upgrading-from-1.rst.inc +++ b/docs/en/rst/upgrading/migrating-from-1.rst.inc @@ -1,7 +1,7 @@ .. This file is included in multiple places, so can't have labels as they appear as duplicates. -The procedure to switch to Git is as follows. The idea is to switch version +The procedure to migrate to Git is as follows. The idea is to switch version control systems without changing the version of Bugzilla you are using, to minimise the risk of conflict or problems. Any major upgrade can then happen as a separate step. @@ -10,14 +10,16 @@ Update Bugzilla To The Latest Point Release =========================================== It is recommended that you switch to Git while using the latest -point release for your major version, so if you aren't running that, you may +point release for your version, so if you aren't running that, you may want to do a minor upgrade first. .. todo:: Is this actually necessary? It adds several extra steps. What are we trying to avoid here? If we do have to do it, can we avoid them having to work out the latest point release manually? And do the bzr and CVS update commands take the full version number including - the third digit, or do they just take major and minor? + the third digit, or do they just take major and minor? We need to + make sure all commands operate on the same version number style, + and that it's clearly explained. First, you need to find what version of Bugzilla you are using. It should be in the top right corner of the front page but, if not, open the file @@ -52,26 +54,3 @@ Then run checksetup to upgrade your database: You should then test your Bugzilla carefully, or just use it for a day or two, to make sure it's all still working fine. - -Download Code from Git -====================== - -Download a copy of your current version of Bugzilla from the git repository -into a separate directory alongside your existing Bugzilla installation -(which we will assume is in a directory called :file:`bugzilla`). - -You will need a copy of the git program. All Linux distributions have it; -search your package manager for "git". On Windows or Mac OS X, you can -`download the official build `_. - -Once git is installed, run these commands to pull a copy of Bugzilla: - -:command:`git clone https://git.mozilla.org/bugzilla/bugzilla bugzilla-new` - -:command:`cd bugzilla-new` - -:command:`git checkout $VERSION` - -Replace $VERSION with the two-digit version number of your current Bugzilla, e.g. -4.2. These command will automatically change your version to the latest -point release of version $VERSION. diff --git a/docs/en/rst/upgrading/upgrading-from-2.rst.inc b/docs/en/rst/upgrading/migrating-from-2.rst.inc similarity index 82% rename from docs/en/rst/upgrading/upgrading-from-2.rst.inc rename to docs/en/rst/upgrading/migrating-from-2.rst.inc index 5d413ed777..e49ca34ed2 100644 --- a/docs/en/rst/upgrading/upgrading-from-2.rst.inc +++ b/docs/en/rst/upgrading/migrating-from-2.rst.inc @@ -1,6 +1,29 @@ .. This file is included in multiple places, so can't have labels as they appear as duplicates. - + +Download Code from Git +====================== + +Download an additional copy of your *current* version of Bugzilla from the git +repository into a separate directory alongside your existing Bugzilla +installation (which we will assume is in a directory called :file:`bugzilla`). + +You will need a copy of the git program. All Linux distributions have it; +search your package manager for "git". On Windows or Mac OS X, you can +`download the official build `_. + +Once git is installed, run these commands to pull a copy of Bugzilla: + +:command:`git clone https://git.mozilla.org/bugzilla/bugzilla bugzilla-new` + +:command:`cd bugzilla-new` + +:command:`git checkout $VERSION` + +Replace $VERSION with the two-digit version number of your current Bugzilla, e.g. +4.2. These command will automatically switch your checkout to be a copy of +the latest point release of version $VERSION. + Save Any Local Customizations ============================= diff --git a/docs/en/rst/upgrading/migrating-from-a-tarball.rst b/docs/en/rst/upgrading/migrating-from-a-tarball.rst new file mode 100644 index 0000000000..b84eacf65b --- /dev/null +++ b/docs/en/rst/upgrading/migrating-from-a-tarball.rst @@ -0,0 +1,25 @@ +.. _migrating-from-a-tarball: + +Migrating from a Tarball +######################## + +.. todo:: Need to check the diff command in the tarball case using a real + tarball and git checkout + +.. |diffcommand| replace:: :command:`diff -ru -x data -x .git ../bugzilla-new . > patch.diff` +.. |extstatusinfo| replace:: Copy across any subdirectories which do not exist + in your new install. + +The procedure to migrate to Git is as follows. The idea is to switch without +changing the version of Bugzilla you are using, to minimise the risk of +conflict or problems. Any major upgrade can then happen as a separate step. + +Find Your Current Bugzilla Version +================================== + +First, you need to find what version of Bugzilla you are using. It should be +in the top right corner of the front page but, if not, open the file +:file:`Bugzilla/Constants.pm` in your Bugzilla directory and search for +:code:`BUGZILLA_VERSION`. + +.. include:: migrating-from-2.rst.inc diff --git a/docs/en/rst/upgrading/upgrading-from-bazaar.rst b/docs/en/rst/upgrading/migrating-from-bzr.rst similarity index 69% rename from docs/en/rst/upgrading/upgrading-from-bazaar.rst rename to docs/en/rst/upgrading/migrating-from-bzr.rst index c368db53c3..ce693ad905 100644 --- a/docs/en/rst/upgrading/upgrading-from-bazaar.rst +++ b/docs/en/rst/upgrading/migrating-from-bzr.rst @@ -1,11 +1,11 @@ -.. _upgrading-from-bazaar: +.. _migrating-from-bazaar: -Upgrading from Bazaar +Migrating from Bazaar ##################### .. |updatecommand| replace:: :command:`bzr up -r tag:bugzilla-$VERSION` .. |diffcommand| replace:: :command:`bzr diff > patch.diff` .. |extstatusinfo| replace:: The command :command:`bzr status extensions/` should help you work out what you added, if anything. -.. include:: upgrading-from-1.rst.inc -.. include:: upgrading-from-2.rst.inc +.. include:: migrating-from-1.rst.inc +.. include:: migrating-from-2.rst.inc diff --git a/docs/en/rst/upgrading/upgrading-from-cvs.rst b/docs/en/rst/upgrading/migrating-from-cvs.rst similarity index 71% rename from docs/en/rst/upgrading/upgrading-from-cvs.rst rename to docs/en/rst/upgrading/migrating-from-cvs.rst index 03456966a6..023b39856a 100644 --- a/docs/en/rst/upgrading/upgrading-from-cvs.rst +++ b/docs/en/rst/upgrading/migrating-from-cvs.rst @@ -1,13 +1,13 @@ -.. _upgrading-from-cvs: +.. _migrating-from-cvs: -Upgrading from CVS +Migrating from CVS ################## .. |updatecommand| replace:: :command:`cvs update -rBUGZILLA-$VERSION-STABLE -dP` .. |diffcommand| replace:: :command:`cvs diff -puN > patch.diff` .. |extstatusinfo| replace:: The command :command:`cvs status extensions/` should help you work out what you added, if anything. -.. include:: upgrading-from-1.rst.inc -.. include:: upgrading-from-2.rst.inc +.. include:: migrating-from-1.rst.inc +.. include:: migrating-from-2.rst.inc diff --git a/docs/en/rst/upgrading/overview.rst b/docs/en/rst/upgrading/overview.rst index cab23521be..e779caf522 100644 --- a/docs/en/rst/upgrading/overview.rst +++ b/docs/en/rst/upgrading/overview.rst @@ -14,10 +14,10 @@ the method by which you obtain the code along the way. to test the upgrade on a development server first, using a copy of the production data and configuration. -Bugzilla uses the Git version control system to store its code. A modern Bugzilla -installation consists of a checkout of a stable version of the code from our -Git repository. This makes upgrading much easier. If this is -true of your installation, see :ref:`upgrading-with-git`. +Bugzilla uses the Git version control system to store its code. A modern +Bugzilla installation consists of a checkout of a stable version of the code +from our Git repository. This makes upgrading much easier. If this is +already true of your installation, see :ref:`upgrading-with-git`. Before Git, we used to use Bazaar and, before that, CVS. If your installation of Bugzilla consists of a checkout from one of those two systems, you need to @@ -27,7 +27,7 @@ upgrade in three steps: 2. move to Git while staying on exactly the same release; 3. upgrade to the latest Bugzilla using the instructions for :ref:`upgrading-with-git`. -See :ref:`upgrading-from-bazaar` or :ref:`upgrading-from-cvs` as appropriate. +See :ref:`migrating-from-bazaar` or :ref:`migrating-from-cvs` as appropriate. Some Bugzillas were installed simply by downloading a copy of the code as an archive file ("tarball"). However, recent tarballs have included source @@ -39,9 +39,10 @@ version control system your copy of Bugzilla recognizes, look for the following subdirectories in your root Bugzilla directory: * :file:`.git`: you installed using Git - follow :ref:`upgrading-with-git` -* :file:`.bzr`: you installed using Bazaar - follow :ref:`upgrading-from-bazaar` -* :file:`CVS`: you installed using CVS - follow :ref:`upgrading-from-cvs` -* none of the above: you installed using an old tarball - follow :ref:`upgrading-with-a-tarball` +* :file:`.bzr`: you installed using Bazaar - follow :ref:`migrating-from-bazaar` +* :file:`CVS`: you installed using CVS - follow :ref:`migrating-from-cvs` +* none of the above: you installed using an old tarball - follow + :ref:`migrating-from-a-tarball` It is also possible, particularly if your server machine does not have and cannot be configured to have access to the public internet, to upgrade using diff --git a/docs/en/rst/upgrading/upgrading-with-1.rst.inc b/docs/en/rst/upgrading/upgrading-with-1.rst.inc new file mode 100644 index 0000000000..4861f6ea90 --- /dev/null +++ b/docs/en/rst/upgrading/upgrading-with-1.rst.inc @@ -0,0 +1,41 @@ +Before You Upgrade +================== + +Before you start your upgrade, there are a few important +steps to take: + +#. Read the + `Release Notes `_ of the version you're + upgrading to and all intermediate versions, particularly the "Notes for + Upgraders" sections, if present. They may make you aware of additional + considerations. + +#. Run the :ref:`sanity-check` on your installation. Attempt to fix all + warnings that the page produces before you start, or it's + possible that you may experience problems during your upgrade. + +#. Work out how to :ref:`back up ` your Bugzilla entirely, and + how to restore from a backup if need be. + +Customized Bugzilla? +-------------------- + +If you have modified the code or templates of your Bugzilla, +then upgrading requires a bit more thought and effort than the simple process +below. See :ref:`template-method` for a discussion of the various methods of +code customization that may have been used. + +The larger the jump you are trying to make, the more difficult it +is going to be to upgrade if you have made local code customizations. +Upgrading from 4.2 to 4.2.1 should be fairly painless even if +you are heavily customized, but going from 2.18 to 4.2 is going +to mean a fair bit of work re-writing your local changes to use +the new files, logic, templates, etc. If you have done no local +changes at all, however, then upgrading should be approximately +the same amount of work regardless of how long it has been since +your version was released. + +If you have made customizations, you should do the upgrade on a test system +with the same configuration and make sure all your customizations still work. +If not, port and test them so you have them ready to reapply once you do +the upgrade for real. diff --git a/docs/en/rst/upgrading/upgrading-with-2.rst.inc b/docs/en/rst/upgrading/upgrading-with-2.rst.inc new file mode 100644 index 0000000000..d8e2dbfaa0 --- /dev/null +++ b/docs/en/rst/upgrading/upgrading-with-2.rst.inc @@ -0,0 +1,32 @@ +Upgrading the Database +====================== + +Run :file:`checksetup.pl`. This will do everything required to convert +your existing database and settings to the new version. + +:command:`cd $BUGZILLA_HOME` + +:command:`./checksetup.pl` + + .. warning:: For some upgrades, running :file:`checksetup.pl` on a large + installation (75,000 or more bugs) can take a long time, + possibly several hours, if e.g. indexes need to be rebuilt. If this + length of downtime would be a problem for you, you can determine + timings for your particular situation by doing a test upgrade on a + development server with the production data. + +:file:`checksetup.pl` may also tell you that you need some additional +Perl modules, or newer versions of the ones you have. You will need to +install these, either system-wide or using the :file:`install-module.pl` +script that :file:`checksetup.pl` recommends. + +Finishing The Upgrade +===================== + +#. Reactivate Bugzilla by clear the text that you put into the + :param:`shutdownhtml` parameter. + +#. Run another :ref:`sanity-check` on your + upgraded Bugzilla. It is recommended that you fix any problems + you see immediately. Failure to do this may mean that Bugzilla + may not work entirely correctly. diff --git a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst index 6910c64806..c38f28a2b0 100644 --- a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst +++ b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst @@ -7,8 +7,24 @@ If you are unable (or unwilling) to use Git, another option is to obtain a tarball of the latest version from our website and upgrade your Bugzilla installation using that. -Download Bugzilla -================= +Without a source code management system to help you, the process may be +trickier. + +.. include:: upgrading-with-1.rst.inc + +As you are using a tarball and not an SCM, it's not at all easy to see if +you've made local code customizations. You may have to use institutional +knowledge, or download a fresh copy of your *current* version of Bugzilla +and compare the two directories. If you find that you have, you'll need +to turn them into a patch file, perhaps by diffing the two directories, +and then reapply that patch file later. If you are customizing Bugzilla +locally, please consider +:ref:`rebasing your install on top of git `. + +.. _upgrade-files-tarball: + +Getting The New Bugzilla +======================== Download a copy of the latest version of Bugzilla from the `Download Page `_ into a separate @@ -16,9 +32,43 @@ directory (which we will call :file:`bugzilla-new`) alongside your existing Bugzilla installation (which we will assume is in a directory called :file:`bugzilla`). -.. |diffcommand| replace:: :command:`diff -u > patch.diff` -.. |extstatusinfo| replace:: With no SCM to help you, you will have to - work out by hand which extensions came with - Bugzilla and which you added. +Copy Across Data and Modules +============================ + +Copy the contents of the following directories from your current installation +of Bugzilla into the corresponding directory in :file:`bugzilla-new/`: + +.. code-block:: none + + lib/ + data/ + template/en/custom (may or may not exist) + +You also need to copy any extensions you have written or installed, which are +in the :file:`extensions/` directory. Bugzilla ships with some extensions, +so again if you want to know if any of the installed extensions are yours, +you may have to compare with a clean copy of your current version. You can +disregard any which have a :file:`disabled` file - those are not enabled. + +Lastly, copy the following file from your current installation of Bugzilla +into the corresponding place in :file:`bugzilla-new/`: + +.. code-block:: none + + localconfig + +This file contains your database password and access details. + +Swap The New Version In +======================= + +Now we swap the directories over. From the directory containing the +:file:`bugzilla` and :file:`bugzilla-new` directories, run: + +:command:`mv bugzilla bugzilla-old` + +:command:`mv bugzilla-new bugzilla` + +:command:`cd bugzilla` -.. include:: upgrading-from-2.rst.inc +.. include:: upgrading-with-2.rst.inc diff --git a/docs/en/rst/upgrading/upgrading-with-git.rst b/docs/en/rst/upgrading/upgrading-with-git.rst index 6bcf29f15c..1d9ba92f3d 100644 --- a/docs/en/rst/upgrading/upgrading-with-git.rst +++ b/docs/en/rst/upgrading/upgrading-with-git.rst @@ -9,50 +9,21 @@ intermediate steps. There is a script named :file:`checksetup.pl` included with Bugzilla that will automatically do all of the database migration for you. -.. _upgrade-before: +.. include:: upgrading-with-1.rst.inc -Before You Upgrade -================== +You can see if you have local code customizations using: -Before you start your upgrade, there are a few important -steps to take: +:command:`git diff` -#. Read the - `Release Notes `_ of the version you're - upgrading to and all intermediate versions, particularly the "Notes for - Upgraders" sections, if present. They may make you aware of additional - considerations. +If that comes up empty, then run: -#. Run the :ref:`sanity-check` on your installation. Attempt to fix all - warnings that the page produces before you start, or it's - possible that you may experience problems during your upgrade. +:command:`git log | head` -#. Work out how to :ref:`back up ` your Bugzilla entirely, and - how to restore from a backup if need be. +and see if the last commit looks like one made by the Bugzilla team, or +by you. If it looks like it was made by us, then you have made no local +code customizations. -.. _upgrade-modified: - -Customized Bugzilla? --------------------- - -If you have modified the code or templates of your Bugzilla, -then upgrading requires a bit more thought and effort than the simple process -below. See :ref:`template-method` for a discussion of the various methods of -customization that may have been used. - -The larger the jump you are trying to make, the more difficult it -is going to be to upgrade if you have made local customizations. -Upgrading from 4.2 to 4.2.1 should be fairly painless even if -you are heavily customized, but going from 2.18 to 4.2 is going -to mean a fair bit of work re-writing your local changes to use -the new files, logic, templates, etc. If you have done no local -changes at all, however, then upgrading should be approximately -the same amount of work regardless of how long it has been since -your version was released. - -You should do the upgrade on a test system with the same configuration and -make sure all your customizations still work. If not, port and test them so -you have them ready for the real thing. +.. _start-upgrade-git: Starting the Upgrade ==================== @@ -62,11 +33,11 @@ When you are ready to go: #. Shut down your Bugzilla installation by putting some explanatory text in the :param:`shutdownhtml` parameter. -#. Make all necessary :ref:`backups`. +#. Make all necessary :ref:`backups `. *THIS IS VERY IMPORTANT*. If anything goes wrong during the upgrade, having a backup allows you to roll back to a known good state. -.. _upgrade-files: +.. _upgrade-files-git: Getting The New Bugzilla ======================== @@ -82,34 +53,9 @@ in which Bugzilla is installed. .. todo:: What is the best way to pull latest stable? -.. _upgrade-database: - -Upgrading the Database -====================== - -Run :file:`checksetup.pl`. This will do everything required to convert -your existing database and settings to the new version. - -:command:`cd $BUGZILLA_HOME` - -:command:`./checksetup.pl` - - .. warning:: For some upgrades, running :file:`checksetup.pl` on a large - installation (75,000 or more bugs) can take a long time, - possibly several hours, if e.g. indexes need to be rebuilt. If this - length of downtime would be a problem for you, you can determine - timings for your particular situation by doing a test upgrade on a - development server with the production data. - -.. _upgrade-finish: - -Finishing The Upgrade -===================== - -#. Reactivate Bugzilla by clear the text that you put into the - :param:`shutdownhtml` parameter. +If you have local code customizations, git will attempt to merge them. If +it fails, then you should implement the plan you came up with when you +detected these customizations in the step above, before you started the +upgrade. -#. Run another :ref:`sanity-check` on your - upgraded Bugzilla. It is recommended that you fix any problems - you see immediately. Failure to do this may mean that Bugzilla - may not work entirely correctly. +.. include:: upgrading-with-2.rst.inc diff --git a/docs/en/rst/using.rst b/docs/en/rst/using.rst deleted file mode 100644 index b6f9e039ff..0000000000 --- a/docs/en/rst/using.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _using: - -============== -Using Bugzilla -============== - -.. toctree:: - :maxdepth: 2 - - using/creating-an-account - using/filing - using/understanding - using/editing - using/finding - using/reports-and-charts - using/tips - using/preferences - diff --git a/docs/en/rst/using/index.rst b/docs/en/rst/using/index.rst new file mode 100644 index 0000000000..a8777558dd --- /dev/null +++ b/docs/en/rst/using/index.rst @@ -0,0 +1,18 @@ +.. _using: + +============== +Using Bugzilla +============== + +.. toctree:: + :maxdepth: 2 + + creating-an-account + filing + understanding + editing + finding + reports-and-charts + tips + preferences +