From: Gervase Markham Date: Fri, 19 Sep 2014 11:49:03 +0000 (+0800) Subject: Reorganize "About", and make all TODO items more clear using todo extension. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3ba9d78ae433af9323446712e416bd992e1e783c;p=thirdparty%2Fbugzilla.git Reorganize "About", and make all TODO items more clear using todo extension. --- diff --git a/docs/en/rst/_static/bugzilla.css b/docs/en/rst/_static/bugzilla.css index 2826b19e78..c8f3529473 100644 --- a/docs/en/rst/_static/bugzilla.css +++ b/docs/en/rst/_static/bugzilla.css @@ -8,3 +8,8 @@ dt { font-weight: bold; } .group { font-family: monospace; } .field { font-weight: bold; } .command { font-family: monospace; font-size: 130% } + +.admonition-todo { + background-color: lightpink; + border: 2px darkred solid; +} diff --git a/docs/en/rst/about.rst b/docs/en/rst/about.rst index 720c5d4cc1..4801e0f3a9 100644 --- a/docs/en/rst/about.rst +++ b/docs/en/rst/about.rst @@ -4,12 +4,124 @@ About This Guide ================ -.. toctree:: - :maxdepth: 2 - - about/introduction - about/evaluating - about/getting-help - about/document-conventions - about/license - about/credits +This is the documentation for version |version| of Bugzilla, a bug-tracking +system from Mozilla. Bugzilla is an enterprise-class piece of software +that tracks millions of bugs and issues for thousands of organizations around +the world. + +The most current version of this document can always be found on the +`Bugzilla website `_. + +.. _evaluating: + +Evaluating Bugzilla +################### + +If you want to try out Bugzilla to see if it meets your needs, you can do so +on `Landfill `_, our test +server. The `Bugzilla FAQ `_ may also +be helpful, as it answers a number of questions people sometimes have about +whether Bugzilla is for them. + +.. _getting-help: + +Getting More Help +################# + +If this document does not answer your questions, we run a +`Mozilla forum `_ +which can be accessed as a newsgroup, mailing list, or over the web as a +Google Group. Please +`search it `_ +first, and then ask your question there. + +If you need a guaranteed response, commercial support is +`available `_ for Bugzilla +from a number of people and organizations. + +.. _conventions: + +Document Conventions +#################### + +This document uses the following conventions: + +.. warning:: This is a warning - something you should be aware of. + +.. note:: This is just a note, for your information. + +A filename or a path to a filename is displayed like this: +:file:`/path/to/filename.ext` + +A command to type in the shell is displayed like this: +:command:`command --arguments` + +A sample of code is illustrated like this: + +:: + + First Line of Code + Second Line of Code + ... + +This documentation is maintained in +`reStructured Text +`_ format using +the `Sphinx `_ documentation system. It has +recently been rewritten, so undoubtedly has bugs. Please file any you find, in +the `Bugzilla Documentation +`_ +component in Mozilla's installation of Bugzilla. If you also want to make a +patch, that would be wonderful. Changes are best submitted as diffs, attached +to a bug. There is a :ref:`Style Guide ` to help you write any +new text and markup. + +.. _license: + +License +####### + +Bugzilla is `free `_ and +`open source `_ software, which means (among other +things) that you can download it, install it and run it for any purpose +whatsoever without the need for license or payment. Isn't that refreshing? + +Bugzilla's code is made available under the +`Mozilla Public License 2.0 `_ (MPL), +specifically the variant which is Incompatible with Secondary Licenses. +However, again, if you only want to install and run Bugzilla, you don't need +to worry about that; it's only relevant if you redistribute the code or any +changes you make. + +Bugzilla's documentation is made available under the +`Creative Commons CC-BY-SA International License 4.0 +`_, +or any later version. + +.. _credits: + +Credits +####### + +The people listed below have made significant contributions to the +creation of this documentation: + +Andrew Pearson, +Ben FrantzDale, +Dave Lawrence, +Dave Miller, +Dawn Endico, +Eric Hanson, +Gervase Markham, +Jacob Steenhagen, +Joe Robins, +Kevin Brannen, +Martin Wulffeld, +Matthew P. Barnson, +Ron Teitelbaum, +Shane Travis, +Spencer Smith, +Tara Hernandez, +Terry Weissman, +Vlad Dascalu, +Zach Lipton. diff --git a/docs/en/rst/about/credits.rst b/docs/en/rst/about/credits.rst deleted file mode 100644 index c3954550f3..0000000000 --- a/docs/en/rst/about/credits.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _credits: - -Credits -####### - -The people listed below have made significant contributions to the -creation of this documentation: - -Andrew Pearson, -Ben FrantzDale, -Dave Lawrence, -Dave Miller, -Dawn Endico, -Eric Hanson, -Gervase Markham, -Jacob Steenhagen, -Joe Robins, -Kevin Brannen, -Martin Wulffeld, -Matthew P. Barnson, -Ron Teitelbaum, -Shane Travis, -Spencer Smith, -Tara Hernandez, -Terry Weissman, -Vlad Dascalu, -Zach Lipton. diff --git a/docs/en/rst/about/document-conventions.rst b/docs/en/rst/about/document-conventions.rst deleted file mode 100644 index 507e704911..0000000000 --- a/docs/en/rst/about/document-conventions.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _conventions: - -Document Conventions -#################### - -This document uses the following conventions: - -.. warning:: This is a warning - something you should be aware of. - -.. note:: This is just a note, for your information. - -A filename or a path to a filename is displayed like this: -:file:`/path/to/filename.ext` - -A command to type in the shell is displayed like this: -:command:`command --arguments` - -A sample of code is illustrated like this: - -:: - - First Line of Code - Second Line of Code - ... - -This documentation is maintained in -`reStructured Text -`_ format using -the `Sphinx `_ documentation system. It has -recently been rewritten, so undoubtedly has bugs. Please file bugs on it in -the `Bugzilla Documentation -`_ -component. If you want to make a patch, that would be wonderful. Changes are -best submitted as diffs, attached to a bug. There is a -:ref:`Style Guide ` to help you write any new text and markup. - diff --git a/docs/en/rst/about/evaluating.rst b/docs/en/rst/about/evaluating.rst deleted file mode 100644 index 8974351626..0000000000 --- a/docs/en/rst/about/evaluating.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _evaluating: - -Evaluating Bugzilla -################### - -If you want to evaluate Bugzilla, you can try it out on -`Landfill `_, our test -server. The `Bugzilla FAQ `_ may also -be helpful, as it answers a number of questions people sometimes have about -whether Bugzilla can do what they need. - diff --git a/docs/en/rst/about/getting-help.rst b/docs/en/rst/about/getting-help.rst deleted file mode 100644 index b126ffb1a1..0000000000 --- a/docs/en/rst/about/getting-help.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _getting-help: - -Getting More Help -################# - -If this document does not answer your questions, we run a -`Mozilla forum `_ -which can be accessed as a newsgroup, mailing list, or over the web as a -Google Group. Please -`search it `_ -first, and then ask your question there. - -If you need a guaranteed response, commercial support is -`available `_ for Bugzilla -from a number of people and organizations. - diff --git a/docs/en/rst/about/introduction.rst b/docs/en/rst/about/introduction.rst deleted file mode 100644 index efdd4bd1bb..0000000000 --- a/docs/en/rst/about/introduction.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _introduction: - -Introduction -############ - -This is the documentation for version |version| of Bugzilla, a bug-tracking -system from Mozilla. Bugzilla is an enterprise-class piece of software -that tracks millions of bugs and issues for thousands of organizations around -the world. - -The most current version of this document can always be found on the -`Bugzilla website `_. diff --git a/docs/en/rst/about/license.rst b/docs/en/rst/about/license.rst deleted file mode 100644 index fae238ed7c..0000000000 --- a/docs/en/rst/about/license.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _license: - -License -####### - -Bugzilla is `free `_ and -`open source `_ software, which means (among other -things) that you can download it, install it and run it for any purpose -whatsoever without the need for license or payment. Isn't that refreshing? - -Bugzilla's code is made available under the -`Mozilla Public License 2.0 `_ (MPL), -specifically the variant which is Incompatible with Secondary Licenses. -However, again, if you only want to install and run Bugzilla, you don't need -to worry about that; it's only relevant if you redistribute the code or any -changes you make. - -Bugzilla's documentation is made available under the -`Creative Commons CC-BY-SA International License 4.0 -`_, -or any later version. - diff --git a/docs/en/rst/administering/categorization.rst b/docs/en/rst/administering/categorization.rst index f9ab5b2bdc..afd191c06f 100644 --- a/docs/en/rst/administering/categorization.rst +++ b/docs/en/rst/administering/categorization.rst @@ -90,7 +90,7 @@ To create a new product: #. Enter the details as outlined above. -XXX This section is pointless; if it's not obvious, we should make it more obvious :-) +.. todo:: This section is pointless; if it's not obvious, we should make it more obvious :-) .. _edit-products: diff --git a/docs/en/rst/administering/flags.rst b/docs/en/rst/administering/flags.rst index 49a8bfba76..4ad60864b1 100644 --- a/docs/en/rst/administering/flags.rst +++ b/docs/en/rst/administering/flags.rst @@ -365,7 +365,7 @@ the flag description. .. COMMENT: flags-admin -.. COMMENT: XXX We should add a "Uses of Flags" section, here, with examples. +.. todo:: We should add a "Uses of Flags" section, here, with examples. .. COMMENT: flags diff --git a/docs/en/rst/administering/keywords.rst b/docs/en/rst/administering/keywords.rst index 4127f262a8..57e4e8164f 100644 --- a/docs/en/rst/administering/keywords.rst +++ b/docs/en/rst/administering/keywords.rst @@ -11,9 +11,11 @@ bugs much easier. Keywords are global, rather than per-product. If the administrator changes a keyword currently applied to any bugs, the keyword cache must be rebuilt -using the :ref:`sanity-check` script. XXXDoes this mean changing the name of the keyword? Is it still true? -Currently keywords cannot -be marked obsolete to prevent future usage. +using the :ref:`sanity-check` script. + +.. todo:: Does this mean changing the name of the keyword? Is it still true? + +Currently keywords cannot be marked obsolete to prevent future usage. Keywords can be created, edited or deleted by clicking the "Keywords" link in the admin page. There are two fields for each keyword - the keyword diff --git a/docs/en/rst/administering/parameters.rst b/docs/en/rst/administering/parameters.rst index d825b8fe92..b191760a18 100644 --- a/docs/en/rst/administering/parameters.rst +++ b/docs/en/rst/administering/parameters.rst @@ -87,7 +87,7 @@ shutdownhtml log in, and your name/password will be accepted here (but nowhere else). - XXX Is this still true? + .. todo:: Is this still true? announcehtml Any text in this field will be displayed at the top of every HTML @@ -227,7 +227,7 @@ attachment_base For added security, you can insert ``%bugid%`` into the URL, which will be replaced with the ID of the current bug that the attachment is on, when you access an attachment. This will limit attachments to accessing only other attachments on the same bug. Remember, though, that all those possible domain names (such as 1234.your.domain.com) must point to this same Bugzilla instance. - XXX So this requires wildcard DNS? We should explain a bit about what is needed here. + .. todo:: So this requires wildcard DNS? We should explain a bit about what is needed here. allow_attachment_deletion If this option is on, administrators will be able to delete the contents @@ -237,12 +237,12 @@ allow_attachment_deletion maxattachmentsize The maximum size (in kilobytes) of attachments to be stored in the database. If a file larger than this size is attached to a bug, Bugzilla will look at the maxlocalattachment parameter to determine if the file can be stored locally on the web server. If the file size exceeds both limits, then the attachment is rejected. Settings both parameters to 0 will prevent attaching files to bugs. - XXX Talk about MySQL max_allowed_packet + .. todo:: Talk about MySQL max_allowed_packet maxlocalattachment The maximum size (in megabytes) of attachments to be stored locally on the web server. If set to a value lower than the :param:`maxattachmentsize` parameter, attachments will never be kept on the local filesystem. - XXX When should people use this feature? + .. todo:: When should people use this feature? .. _param-bug-change-policies: @@ -392,7 +392,9 @@ For more information on Groups and Group Security, see makeproductgroups Determines whether or not to automatically create groups when new products are created. If this is on, the groups will be - used for querying bugs. XXX This is spectacularly unclear. + used for querying bugs. + + .. todo:: This is spectacularly unclear. chartgroup The name of the group of users who can use the 'New Charts' feature. Administrators should ensure that the public categories and series definitions do not divulge confidential information before enabling this for an untrusted population. If left blank, no users will be able to use New Charts. @@ -627,7 +629,9 @@ whinedays in the CONFIRMED state before notifying people they have untouched new bugs. If you do not plan to use this feature, simply do not set up the whining cron job described in the installation - instructions, or set this value to "0" (never whine). XXXlink + instructions, or set this value to "0" (never whine). + + .. todo:: link globalwatchers This allows you to define specific users who will @@ -647,7 +651,7 @@ features of the Patch Viewer. Bonsai is a tool that enables queries to a CVS tree. LXR is a tool that can cross reference and index source code. -XXX Does anyone use this stuff any more? +.. todo:: Does anyone use this stuff any more? cvsroot The CVS root that most users of your system will be using for 'cvs diff'. Used in Patch Viewer ('Diff' option on patches) to figure out where patches are rooted even if users did the 'cvs diff' from different places in the directory structure. (NOTE: if your CVS repository is remote and requires a password, you must either ensure the Bugzilla user has done a 'cvs login' or specify the password as part of the CVS root.) Leave this blank if you have no CVS repository. diff --git a/docs/en/rst/conf.py b/docs/en/rst/conf.py index a298f2ced9..6a0349b95e 100644 --- a/docs/en/rst/conf.py +++ b/docs/en/rst/conf.py @@ -370,3 +370,5 @@ pdf_use_numbered_links = True # Background images fitting mode pdf_fit_background_mode = 'scale' + +todo_include_todos = True diff --git a/docs/en/rst/customizing/templates.rst b/docs/en/rst/customizing/templates.rst index 77337b912b..433d339da9 100644 --- a/docs/en/rst/customizing/templates.rst +++ b/docs/en/rst/customizing/templates.rst @@ -106,7 +106,9 @@ Template Toolkit to do this (or the 'uri' filter to encode special characters in URLs). If you forget, you may open up your installation to cross-site scripting attacks. -XXXMOVE Editing templates is a good way of doing a 'poor man's custom +.. todo:: Move the below. + +Editing templates is a good way of doing a 'poor man's custom fields'. For example, if you don't use the :guilabel:`Status Whiteboard`, but want to have a free-form text entry box for :guilabel:`Build Identifier`, @@ -198,7 +200,7 @@ customizing for your installation. your Bugzilla installation. :file:`global/variables.none.tmpl`: - XXX Need to describe the use of this file + .. todo:: Need to describe the use of this file :file:`list/table.html.tmpl`: This template controls the appearance of the bug lists created diff --git a/docs/en/rst/customizing/writing-extensions.rst b/docs/en/rst/customizing/writing-extensions.rst index c2796bb3fa..12bc1ca3b1 100644 --- a/docs/en/rst/customizing/writing-extensions.rst +++ b/docs/en/rst/customizing/writing-extensions.rst @@ -8,8 +8,8 @@ documentation <../html/api/Bugzilla/Extension.html>`_ for the core documentation on how to write an Extension. We also have some additional tips and tricks here. -XXX These came from the wiki. Should they actually be integrated into the -POD, or should some of the POD come here, or something else? +.. todo:: These came from the wiki. Should they actually be integrated into the + POD, or should some of the POD come here, or something else? Checking Syntax =============== diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst index d0351c429a..7834f84c25 100644 --- a/docs/en/rst/installing/apache.rst +++ b/docs/en/rst/installing/apache.rst @@ -43,7 +43,7 @@ Apache with mod_cgi To configure your Apache web server to work with Bugzilla while using mod_cgi, do the following: -XXX Shouldn't we be using sites-available/sites-enabled here? +.. todo:: Shouldn't we be using sites-available/sites-enabled here? #. Edit the Apache configuration file (see above). @@ -102,7 +102,7 @@ and mod_perl. .. warning:: You should also ensure that you have disabled ``KeepAlive`` support in your Apache install when utilizing Bugzilla under mod_perl - XXX How? Why? + .. todo:: How? Why? On restarting Apache, Bugzilla should now be running within the mod_perl environment. diff --git a/docs/en/rst/installing/email.rst b/docs/en/rst/installing/email.rst index d250857859..fd7458624b 100644 --- a/docs/en/rst/installing/email.rst +++ b/docs/en/rst/installing/email.rst @@ -13,8 +13,8 @@ or run one yourself on the Bugzilla machine. Bugzilla's approach to email is configured in the :guilabel:`Email` section of the Parameters. -XXX Bug: description of mail_delivery_method talks about Qmail, and is in -other ways wrong. +.. todo:: Bug: description of mail_delivery_method talks about Qmail, and is in + other ways wrong. .. _install-MTA: @@ -58,7 +58,7 @@ Run Your Own Mail Server This section corresponds to choosing a :param:`mail_delivery_method` of :paramval:`Sendmail`. -XXX Do we still need this? Why would anyone want to do this in 2014? +.. todo:: Do we still need this? Why would anyone want to do this in 2014? Unless you know what you are doing, and can deal with the possible problems of spam, bounces and blacklists, it is probably unwise to set up your own diff --git a/docs/en/rst/installing/iis.rst b/docs/en/rst/installing/iis.rst index 26054260b2..a2d616227d 100644 --- a/docs/en/rst/installing/iis.rst +++ b/docs/en/rst/installing/iis.rst @@ -65,4 +65,4 @@ such as :file:`localconfig` and your :file:`data` directory are secured. -XXX See also https://wiki.mozilla.org/Installing_under_IIS_7.5 +.. todo:: See also https://wiki.mozilla.org/Installing_under_IIS_7.5 diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst index 47907e405c..c8b33fd63a 100644 --- a/docs/en/rst/installing/linux.rst +++ b/docs/en/rst/installing/linux.rst @@ -12,12 +12,12 @@ of additional configuration required. If you are installing your machine from scratch, :ref:`quick-start` may be the best instructions for you. -XXX What's our current position on Debian/Ubuntu packages of Bugzilla? Are -there any, and are they any good? +.. todo:: What's our current position on Debian/Ubuntu packages of Bugzilla? Are + there any, and are they any good? -XXX Which versions of RHEL have packages new enough for us to support them? +.. todo:: Which versions of RHEL have packages new enough for us to support them? -XXX What's the right order for all these steps? +.. todo:: What's the right order for all the following steps? Install Packages ================ @@ -116,7 +116,7 @@ Bugzilla-only copy of the newer version. At this point, you need to :file:`su` to root. You should remain as root until the end of the install. -XXX Is this true, if they are installing modules locally? +.. todo:: Is this true, if they are installing modules locally? To check whether you have all the required modules and what is still missing, run: @@ -141,7 +141,7 @@ Or, you can pass an individual module name: distribution you are using, but are often called :file:`-devel`. - XXX Give examples for Debian/Ubuntu and RedHat? + .. todo:: Give examples for Debian/Ubuntu and RedHat? .. _config-webserver: @@ -159,7 +159,7 @@ We have specific instructions for the following: You can run :command:`testserver.pl http://bugzilla-url/` from the command line to check if your web server is correctly configured. -XXX Does this work before doing any localconfig stuff? +.. todo:: Does this work before doing any localconfig stuff? .. _config-database: @@ -246,7 +246,7 @@ you should see the Bugzilla front page. Next, do the :ref:`post-install-config`. -XXXX How to we integrate the below (copied from the wiki)? +.. todo:: How to we integrate the below (copied from the wiki)? Gentoo ====== diff --git a/docs/en/rst/installing/mysql.rst b/docs/en/rst/installing/mysql.rst index b6e9d8eb16..229676faf7 100644 --- a/docs/en/rst/installing/mysql.rst +++ b/docs/en/rst/installing/mysql.rst @@ -60,7 +60,7 @@ on Linux. By default, MySQL will only allow you to insert things into the database that are smaller than 1MB. -XXX Is this still true? It's 16MB on Ubuntu 14.04... +.. todo:: Is this still true? It's 16MB on Ubuntu 14.04... Bugzilla attachments may be larger than this. Also, Bugzilla combines all comments diff --git a/docs/en/rst/installing/post-install-config.rst b/docs/en/rst/installing/post-install-config.rst index d5a8a0094d..b94f12956a 100644 --- a/docs/en/rst/installing/post-install-config.rst +++ b/docs/en/rst/installing/post-install-config.rst @@ -43,7 +43,7 @@ section, and change or clear the :param:`createemailregexp` parameter. Optional ======== -XXXHACKME +.. todo:: HACKME Bugzilla has a number of optional features. This section describes how to configure or enable them. diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst index e433d52801..f58e53a97b 100644 --- a/docs/en/rst/installing/quick-start.rst +++ b/docs/en/rst/installing/quick-start.rst @@ -70,8 +70,8 @@ home page. It requires a little familiarity with Linux and the command line. You will get a notification about having a detached HEAD. Don't worry, your head is still firmly on your shoulders. - XXX is this the right way to get the current bugzilla-stable code? Or - should we pull directly from a branch? + .. todo:: is this the right way to get the current bugzilla-stable code? Or + should we pull directly from a branch? 5. Configure MySQL @@ -88,11 +88,11 @@ home page. It requires a little familiarity with Linux and the command line. Save and exit. - XXX default value of maxattachmentsize is 1MB. Default value of max_allowed_packet - is 16MB. Should we just omit this step entirely, for simplicity? Do we need - ft_min_word_len changed? + .. todo:: default value of maxattachmentsize is 1MB. Default value of max_allowed_packet + is 16MB. Should we just omit this step entirely, for simplicity? Do we need + ft_min_word_len changed? - XXX docs for maxattachmentsize should mention max_allowed_packet. File bug. + .. todo:: docs for maxattachmentsize should mention max_allowed_packet. File bug. Restart MySQL: @@ -144,8 +144,8 @@ home page. It requires a little familiarity with Linux and the command line. * Line 67: set ``$db_pass`` to the MySQL root user password you created when installing Ubuntu - XXX Given this is a quick setup on a dedicated box, is it OK to use the - MySQL root user? + .. todo:: Given this is a quick setup on a dedicated box, is it OK to use the + MySQL root user? 10. Check Setup (again) @@ -164,7 +164,7 @@ home page. It requires a little familiarity with Linux and the command line. All the tests should pass. (Note: currently, the first one will give a warning instead. You can ignore that. Bug 1040728.) - XXX Also, Chart::Base gives deprecation warnings :-| + .. todo:: Also, Chart::Base gives deprecation warnings :-| 12. Access Via Web Browser @@ -211,6 +211,6 @@ home page. It requires a little familiarity with Linux and the command line. Click :guilabel:`Save Changes` at the bottom of the page. - XXX There should be a "send test email" button on that page + .. todo:: There should be a "send test email" button on that page And you're all ready to go. :-) diff --git a/docs/en/rst/installing/sqlite.rst b/docs/en/rst/installing/sqlite.rst index 09e5db3c3d..390159ada8 100644 --- a/docs/en/rst/installing/sqlite.rst +++ b/docs/en/rst/installing/sqlite.rst @@ -11,7 +11,7 @@ Once you have SQLite installed, no additional configuration is required to run Bugzilla. Simply set ``$db_driver`` to ``Sqlite`` (case-sensitive) in :file:`localconfig`, when you get to that point in the installation. -XXX This doesn't work - gives a timezone-related error on my box. +.. todo:: This doesn't work - gives a timezone-related error on my box. The database will be stored in :file:`data/db/$db_name`, where ``$db_name`` is the database name defined in :file:`localconfig`. diff --git a/docs/en/rst/integrating/tips.rst b/docs/en/rst/integrating/tips.rst index d7b8c04f4c..4c0961aa6a 100644 --- a/docs/en/rst/integrating/tips.rst +++ b/docs/en/rst/integrating/tips.rst @@ -3,4 +3,4 @@ Integration Tips ################ -XXX Do we have any of these? +.. todo:: Do we have any of these? diff --git a/docs/en/rst/upgrading/upgrading-from-1.rst.inc b/docs/en/rst/upgrading/upgrading-from-1.rst.inc index 37cb7f8b03..0fc333e94f 100644 --- a/docs/en/rst/upgrading/upgrading-from-1.rst.inc +++ b/docs/en/rst/upgrading/upgrading-from-1.rst.inc @@ -1,5 +1,8 @@ +.. 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 -control systems without changing the exact version of Bugzilla you are using, +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. @@ -7,7 +10,11 @@ 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. +point release for your major 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? 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 @@ -43,8 +50,6 @@ 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. -.. _get-from-git: - Download Code from Git ====================== diff --git a/docs/en/rst/upgrading/upgrading-from-2.rst.inc b/docs/en/rst/upgrading/upgrading-from-2.rst.inc index ebe8c84f9c..e7213da0b9 100644 --- a/docs/en/rst/upgrading/upgrading-from-2.rst.inc +++ b/docs/en/rst/upgrading/upgrading-from-2.rst.inc @@ -1,3 +1,6 @@ +.. This file is included in multiple places, so can't have labels as they + appear as duplicates. + Save Any Local Customizations ============================= diff --git a/docs/en/rst/upgrading/upgrading-from-bazaar.rst b/docs/en/rst/upgrading/upgrading-from-bazaar.rst index 3957b91a33..c368db53c3 100644 --- a/docs/en/rst/upgrading/upgrading-from-bazaar.rst +++ b/docs/en/rst/upgrading/upgrading-from-bazaar.rst @@ -7,5 +7,5 @@ Upgrading from Bazaar .. |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 -.. include:: upgrading-from-2.rst +.. include:: upgrading-from-1.rst.inc +.. include:: upgrading-from-2.rst.inc diff --git a/docs/en/rst/upgrading/upgrading-from-cvs.rst b/docs/en/rst/upgrading/upgrading-from-cvs.rst index 8e210e5f00..03456966a6 100644 --- a/docs/en/rst/upgrading/upgrading-from-cvs.rst +++ b/docs/en/rst/upgrading/upgrading-from-cvs.rst @@ -7,7 +7,7 @@ Upgrading from CVS .. |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 -.. include:: upgrading-from-2.rst +.. include:: upgrading-from-1.rst.inc +.. include:: upgrading-from-2.rst.inc diff --git a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst index 1a9c5d97bf..6910c64806 100644 --- a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst +++ b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst @@ -21,4 +21,4 @@ Bugzilla installation (which we will assume is in a directory called work out by hand which extensions came with Bugzilla and which you added. -.. include:: upgrading-from-2.rst +.. include:: upgrading-from-2.rst.inc diff --git a/docs/en/rst/upgrading/upgrading-with-git.rst b/docs/en/rst/upgrading/upgrading-with-git.rst index 8221beaa3f..a7067eba2d 100644 --- a/docs/en/rst/upgrading/upgrading-with-git.rst +++ b/docs/en/rst/upgrading/upgrading-with-git.rst @@ -23,8 +23,8 @@ steps to take: Upgraders" sections, if present. They may make you aware of additional considerations. - XXX We need to make these more accessible - they are currently rather hard - to find. We could collate them on a single page with no intervening cruft. +.. todo:: We need to make these more accessible - they are currently rather hard + to find. We could collate them on a single page with no intervening cruft. #. Run the :ref:`sanity-check` on your installation. Attempt to fix all warnings that the page produces before you start, or it's @@ -84,7 +84,7 @@ in which Bugzilla is installed. :command:`git pull` -XXX What is the best way to pull latest stable? +.. todo:: What is the best way to pull latest stable? .. _upgrade-database: diff --git a/docs/en/rst/using/finding.rst b/docs/en/rst/using/finding.rst index 578a4f04f6..e8e1314838 100644 --- a/docs/en/rst/using/finding.rst +++ b/docs/en/rst/using/finding.rst @@ -97,7 +97,7 @@ There are three fields in each row of a boolean search. Multiple Charts --------------- -XXX This needs rewriting for the new UI. +.. todo:: This needs rewriting for the new UI. The terms within a single row of a boolean chart are all constraints on a single piece of data. If you are looking for @@ -243,7 +243,7 @@ Remember Search As: Adding and Removing Tags on Bugs ================================ -XXX Looks like you can no longer do this from search results; is that right? +.. todo:: Looks like you can no longer do this from search results; is that right? You can add and remove tags from individual bugs, which let you find and manage bugs more easily. Tags are per-user and so are only visible and editable