Closed Bug 371020 Opened 17 years ago Closed 16 years ago

Overhaul the "Upgrading to a New Release" section

Categories

(Bugzilla :: Documentation, defect)

2.23.4
defect
Not set
normal

Tracking

()

RESOLVED FIXED
Bugzilla 3.0

People

(Reporter: mkanat, Assigned: mkanat)

References

Details

Attachments

(1 file, 1 obsolete file)

I think this section should be up near Installation and Configuration.

Also, it needs to explain all the steps that I explain in the Release Notes, so that the Release Notes don't always have to contain the upgrade instructions. These steps are:

--------------------
NOTE: Upgrading from a large installation (over 10,000 bugs) running 2.18
      or before 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.

1) Read these entire Release Notes, particularly the "Notes for Upgraders"
   section above.

2) 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.

3) Make a backup of the Bugzilla database before you upgrade, perhaps
   by using mysqldump. THIS IS VERY IMPORTANT. If anything goes wrong
   during the upgrade, your installation can be corrupted beyond
   recovery. Having a backup keeps you safe.

   Example:

      mysqldump -u root -p bugs > bugs-db.sql

4) 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.

   You can also use a brand-new Bugzilla directory, as long as you
   copy over the old data/ directory and the "localconfig" file to the
   new installation.

5) Run checksetup.pl after you install the new version.

7) View the Sanity Check page again after you run checksetup.pl.

8) 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.
Okay, I am SICK of answering questions about this on the mailing list. I'm going to re-write this section myself.
Assignee: documentation → mkanat
Max - Since your comment in June, have you done anything :) If not, I'll make this one my next project.

-Sam
Status: NEW → ASSIGNED
Assignee: mkanat → sam.folkwilliams
Status: ASSIGNED → NEW
(In reply to comment #2)
> Max - Since your comment in June, have you done anything :) If not, I'll make
> this one my next project.

  Yep, haven't done anything! :-)
Okay, I'm going to do this myself, now.
Assignee: sam.folkwilliams → mkanat
Attached patch v1 (obsolete) — Splinter Review
Well, I got to learn Docbook, that was fun. I may have not done some things in the best possible way--just let me know, if that's the case.

I also moved this section into the Installing section (where people expect to find it), instead of the *very bottom* of the Administration section, where nobody ever finds it.
Attachment #332617 - Flags: review?(colin.ogilvie)
Attachment #332617 - Flags: review?(LpSolit)
Attachment #332617 - Flags: review?(colin.ogilvie) → review?(documentation)
Xiaoou--I've provided some backup commands for PostgreSQL and MySQL in this documentation. Do you want to give me a similar one for Oracle?
Status: NEW → ASSIGNED
Target Milestone: --- → Bugzilla 3.0
Also, for anybody who wants to read it, I currently have it rendered at:

  https://landfill.bugzilla.org/mkanat4/docs/en/html/upgrade.html
Comment on attachment 332617 [details] [diff] [review]
v1

>+        <listitem>
>+          <para>
>+            View the Sanity Check (<xref linkend="sanitycheck"/>) page in your
>+            upgraded Bugzilla.
>+          </para>

Nit: as you suggested to put something in shutdownhtml before upgrading, maybe should you request to clear this parameter before running sanitycheck.cgi, else it won't run. Otherwise looks good. r=LpSolit
Attachment #332617 - Flags: review?(LpSolit) → review+
Attached patch v2Splinter Review
Okay, here's the version with the fix, that I'm going to check in.
Attachment #332617 - Attachment is obsolete: true
Attachment #332628 - Flags: review+
Attachment #332617 - Flags: review?(documentation)
Docs don't need approval, but granting it anyway to note which branches this is going on.
Flags: approval3.2+
Flags: approval3.0+
Flags: approval+
Summary: "Upgrading to a New Release" section needs an overhaul → Overhaul the "Upgrading to a New Release" section
tip:

Checking in docs/en/xml/administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/en/xml/administration.xml,v  <--  administration.xml
new revision: 1.91; previous revision: 1.90
done
Checking in docs/en/xml/installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/en/xml/installation.xml,v  <--  installation.xml
new revision: 1.158; previous revision: 1.157
done

3.2 branch:

Checking in docs/en/xml/administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/en/xml/administration.xml,v  <--  administration.xml
new revision: 1.90.2.1; previous revision: 1.90
done
Checking in docs/en/xml/installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/en/xml/installation.xml,v  <--  installation.xml
new revision: 1.157.2.1; previous revision: 1.157
done

3.0 branch:
Checking in docs/xml/administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/Attic/administration.xml,v  <--  administration.xml
new revision: 1.70.2.14; previous revision: 1.70.2.13
done
Checking in docs/xml/installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/Attic/installation.xml,v  <--  installation.xml
new revision: 1.136.2.14; previous revision: 1.136.2.13
done

Status: ASSIGNED → RESOLVED
Closed: 16 years ago
Resolution: --- → FIXED
(In reply to comment #6)
> Xiaoou--I've provided some backup commands for PostgreSQL and MySQL in this
> documentation. Do you want to give me a similar one for Oracle?


Max, there are several ways of backuping the database, one simple way is using exp:

exp username/password@SID file=bugzilla.dmp owner=username log=bugzilla.log

i.e.

exp bugs/bugs@XE file=bugzilla.dmp owner=bugs log=bugzilla.log

in which username and password are all "bugs", SID is "XE"

One comment... I'd suggest we update the example instructions to be a more modern release than 2.22.1 :)
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Created:
Updated:
Size: