Unordered mismash of upgrade instructions

Jo_Rhett · November 26, 2014, 10:32pm

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m liking the changes. Glad to see RTFM integrated. My one big question here that I think the documentation could definitely improve upon, is what order to do the changes in? There are changes in every one of these pages and there’s no clear outline for which ones go first.

https://www.bestpractical.com/docs/rt/4.2/README.html
https://www.bestpractical.com/docs/rt/4.2/UPGRADING-3.8.html
https://www.bestpractical.com/docs/rt/4.2/UPGRADING-4.0.html
https://www.bestpractical.com/docs/rt/4.2/UPGRADING-4.2.html
https://www.bestpractical.com/docs/rt/4.2/UPGRADING.mysql.html

I build the new installation on a new system so I’ve done a test upgrade the following way — totally just guessing which things to do in which order. Can someone take a moment to validate if I did it right?

Loaded a backup of the running system’s database, renamed to rt4
Installed apache2 and mod_perl2, set up vhost according to Web deployment - RT 4.2.17 Documentation - Best Practical
Download 4.2.9, extract, ./configure --with-web-handler=modperl2 --with-web-user=apache --with-web-group=apache
sudo make fixdeps
make install
perl etc/upgrade/upgrade-mysql-schema.pl rt4 rt_user password > ~/update.sql
(read and saw only changes to utf8)
mysql -u rt-user -p rt4 < ~/update.sql
Cleanup from UPGRADING-3.8
$ cd /opt/rt4
$ perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/shrink_transactions_table.pl
$ perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/vulnerable-passwords
$ perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/vulnerable-passwords --fix
$ perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/split-out-cf-categories
Database upgrade
$ perl -I/opt/rt4/local/lib -I/opt/rt4/lib sbin/rt-setup-database --action upgrade --prompt-for-dba-password
$ perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/upgrade-articles
$ sbin/rt-validator --check
$ sbin/rt-validator --check --resolve

I’m thinking that perhaps step 8 should have been done before 6 and 7, but it seems to have worked and it displays the tickets and seems to operate properly.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Jo_Rhett · December 3, 2014, 7:20am

Likewise on this one. I’d appreciate a response from Best Practice as to the proper ordering for an upgrade…On Nov 26, 2014, at 2:32 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m liking the changes. Glad to see RTFM integrated. My one big question here that I think the documentation could definitely improve upon, is what order to do the changes in? There are changes in every one of these pages and there’s no clear outline for which ones go first.

README - RT 4.2.17 Documentation - Best Practical
UPGRADING-3.8 - RT 4.2.17 Documentation - Best Practical
UPGRADING-4.0 - RT 4.2.17 Documentation - Best Practical
UPGRADING-4.2 - RT 4.2.17 Documentation - Best Practical
UPGRADING.mysql - RT 4.2.17 Documentation - Best Practical

I build the new installation on a new system so I’ve done a test upgrade the following way — totally just guessing which things to do in which order. Can someone take a moment to validate if I did it right?

Loaded a backup of the running system’s database, renamed to rt4

Installed apache2 and mod_perl2, set up vhost according to Web deployment - RT 4.2.17 Documentation - Best Practical

Download 4.2.9, extract, ./configure --with-web-handler=modperl2 --with-web-user=apache --with-web-group=apache

sudo make fixdeps

make install

perl etc/upgrade/upgrade-mysql-schema.pl rt4 rt_user password > ~/update.sql
(read and saw only changes to utf8)

mysql -u rt-user -p rt4 < ~/update.sql

Cleanup from UPGRADING-3.8
$ cd /opt/rt4
$ perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/shrink_transactions_table.pl
$ perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/vulnerable-passwords
$ perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/vulnerable-passwords --fix
$ perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/split-out-cf-categories

Database upgrade
$ perl -I/opt/rt4/local/lib -I/opt/rt4/lib sbin/rt-setup-database --action upgrade --prompt-for-dba-password
$ perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/upgrade-articles
$ sbin/rt-validator --check
$ sbin/rt-validator --check --resolve

I’m thinking that perhaps step 8 should have been done before 6 and 7, but it seems to have worked and it displays the tickets and seems to operate properly.

–
Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Alex_Vandiver · December 4, 2014, 10:08pm

Iï¿½m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. Iï¿½m
liking the changes. Glad to see RTFM integrated. My one big question
here that I think the documentation could definitely improve upon, is
what order to do the changes in? There are changes in every one of
these pages and thereï¿½s no clear outline for which ones go first.

README - RT 4.2.17 Documentation - Best Practical

Step (2) and (6b) of this address the other files. The top of
UPGRADING.mysql even tells you to start there. A bug in the POD → html
(now fixed) causes it to not show up in the website, but it’s in the
shipped docs/UPGRADING.mysql in the source tarball.

Iï¿½m thinking that perhaps step 8 should have been done before 6 and 7,
but it seems to have worked and it displays the tickets and seems to
operate properly.

We recommend doing the ‘make upgrade-database’ steps before running the
various cleanups in docs/UPGRADING-*

Patches accepted of updates that you think would clarify the issue.

Alex

Jo_Rhett · December 15, 2014, 1:19am

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m
liking the changes. Glad to see RTFM integrated. My one big question
here that I think the documentation could definitely improve upon, is
what order to do the changes in? There are changes in every one of
these pages and there’s no clear outline for which ones go first.

README - RT 4.2.17 Documentation - Best Practical
…(list of files)…

Step (2) and (6b) of this address the other files.

These are the sections of which my complaint is generated. Yes, they list the entire stack of docs which should be read. That’s how I knew the list I posted. But there is no ordering information included here.

The top of
UPGRADING.mysql even tells you to start there. A bug in the POD → html
(now fixed) causes it to not show up in the website, but it’s in the
shipped docs/UPGRADING.mysql in the source tarball.

Yes the revised page is more clear. It’s still not the easiest to track instruction. You could easily demonstrate this with screenshots in a way that someone could follow.

Furthermore, this phrasing is very confusing and implies that nothing else in the documentation applies.

• You are upgrading RT from a version prior to 3.8.0, on any version of MySQL

• You are migrating from MySQL 4.0 to MySQL 4.1 or above

If neither of the above cases apply, your should upgrade as per the instructions in the README.

So if I am upgrading MySQL 5.1 with RT 3.8.5 I shouldn’t read any farther, right? I don’t think that’s what you intended to say.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Alex_Vandiver · December 15, 2014, 8:09pm

Step (2) and (6b) of this address the other files.

These are the sections of which my complaint is generated. Yes, they
list the entire stack of docs which should be read. Thatï¿½s how I
knew the list I posted. But there is no ordering information included
here.

We’ve not previously had explicit documentation on it because there’s no
strict ordering – so we didn’t specify it. I’ve pushed b49f950b to
4.0-trunk which gives a more explicit ordering. Would that have
sufficed to answer your question?

Yes the revised page is more clear. Itï¿½s still not the easiest to
track instruction. You could easily demonstrate this with screenshots
in a way that someone could follow.

What screenshots would you find useful?

Furthermore, this phrasing is very confusing and implies that nothing
else in the documentation applies.

ï¿½ You are upgrading RT from a version prior to 3.8.0, on any
version of MySQL

ï¿½ You are migrating from MySQL 4.0 to MySQL 4.1 or above

If neither of the above cases apply, your should upgrade as per the
instructions in the README.

So if I am upgrading MySQL 5.1 with RT 3.8.5 I shouldnï¿½t read any
farther, right? I donï¿½t think thatï¿½s what you intended to say.

If you’re upgrading MySQL 5.1 with RT 3.8.5, you should just follow the
upgrading instructions in the README; UPGRADING.mysql does indeed not
apply. So yes, you have interpreted as we intended. If you have
suggested clarifications, I’d be glad to hear them.

Alex