Permalink
Fetching contributors…
Cannot retrieve contributors at this time
775 lines (587 sloc) 22.1 KB

NAME

slash1toslash2 - Convert Slash 1.0 database to Slash 2.0

SYNOPSIS

install-slashsite -u slash
slash1toslash2 -u slash slashdotrc.pl

DESCRIPTION

Please read these instructions before starting a new Slash 2.0 site. They are designed to convert a site from scratch; they will not work with a Slash 2.0 site that's been used.

This program will copy data from your old Slash 1.0 database to your new Slash 2.0 database, making direct connections to both databases and copying the data directly between them.

It will copy over your data, but if you've done any customizations to display blocks, or code, it will not copy that over.

A detailed description of the work done is below, "DETAILS". You might want to read this section before running the program.

Note that this is designed for converting a Slash 1.0.9 database; any schema changes you've made, or incompatible changes from earlier versions of Slash, may break this program.

Please follow these instructions precisely to convert your Slash 1.0 site to Slash 2.0.

Requirements

  • You will need a new database to copy the new data to. This could be on the same database server as the Slash 1.0 data, but because the installed modules (specifically, Slash.pm) are not compatible between the sites, you will most likely want to have the installed code for 1.0 and 2.0 on separate boxes.

  • You will need Slash 2.0 installed on some box.

  • You will need access to both the 1.0 and 2.0 databases from the same box. The program will be run from the box that has Slash 2.0 installed, so if that box does not have access to the Slash 1.0 database, you will need to either temporarily edit the mysql.user table of the 1.0 server to grant access, or copy the database from the 1.0 server to the 2.0 server.

BACK UP YOUR DATA

If you lose your data, it is your problem, not ours. I deleted all of the data on http://use.perl.org/ while preparing this program. However, I had a backup ready to go (although I still lost about 12 hours of data, and I feel like an idiot). Back up your data on your Slash 1.0 database. You have been warned.

Also, consider what happens if you have two Slash sites on one machine; what if you give this program the wrong virtual user? Perhaps you just deleted a working site! Back up any existing data on the target database server, too. See, even after writing this warning, I did this, too, and typed "slash" as my virtual user instead of "useperl", and I overwrote some of the existing database, and didn't have a backup for some of it. After that, I felt like a total moron.

This program does not write to your Slash 1.0 database, so you should be fine, but there are no warranties, expressed or implied. If you are running a Slash site, you should be backing up your database nightly anyway, right?

So backup all your data on both boxes, so you don't feel like a moron, like me.

Database Preparation

You probably won't need to change any data. But there are three things to check before starting.

  • Make sure that there are no author/user nickname conflicts. In Slash 1.0, users (nicknames) and authors (AID) were separate, so you could have a user named timothy and an author named timothy, who were not the same person. This is not allowed in Slash 2.0, as those tables have been combined.

    Also, every author must have a matching user, or this will fail. If you still have a story owned by "God", for example, you need a user with nickname "God" and matchname "god".

    Most sites won't have this problem, but if yours does, it is sufficient to change the nickname/matchname fields of any conflicting user, and then have the author create a new account with that name. Of course, make sure the other user knows you are making the change, and try to compensate him in some way, perhaps by giving him extra karma.

    If you decide you would rather change the author's name, then you will need to go through the database, in every field named "aid" (except for the poll tables, where "aid" is "answer id", not "author id") and change the name of that author.

    Changing the name of the user is easier.

  • Select a user ID (UID) to be your "anonymous coward" (AC). This should probably be the lowest positive integer not in use on the Slash 1.0 site. It could be one of the six default users, or a test user you created.

    Be careful to pick a user that does not have any comments or anything else in the system. If there is no UID not in use, create a new test user (as you would create any user, through users.pl) and use that UID.

  • Decide whether or not you want to keep the new admin account created in your Slash 2.0 database. Chances are, you won't want to or need to.

    However, if you do want to keep it, then you need to delete/modify all references to that user's uid in your Slash 1.0 database. It is easier if you just allow this program to delete that uid from your Slash 2.0 database, though, so there is no conflict.

Install Slash 2.0 Slash Site

Run the install-slashsite program as described in that program's documentation. Remember which virtual user you used to install the site. Do not make any changes to the database.

Copy Slash 1.0 RC File

Get the slashdotrc.pl file from your Slash 1.0 site and copy it to some directory on your Slash 2.0 box. At this point, make sure you can access the Slash 1.0 database from the Slash 2.0 box.

You may need to modify the slashdotrc.pl file's dbhost, dbuser, and dbpass variables to make sure the database can be accessed properly. Also, make sure "$Slash::conf{DEFAULT}" is not commented out in slashdotrc.pl.

Run It

Run the program, using the proper value for virtual_user and the proper path to the slashdotrc.pl file:

slash1toslash2 -u virtual_user slashdotrc.pl

You will be asked three questions: do you agree to the disclaimer, what UID do you want for AC (default is 1), and do you want to delete the new admin user created by install-slashsite (probably yes).

Add Final Touches

Copy over any images or static files you have, and adjust the site's templates, blocks, and variables as needed.

DETAILS

This is just a detailed run-down of what the program does, in the order it does it.

  • If you chose an AC UID of other than 1, then the new UID is deleted from each of the users* tables, and the old AC UID (1) is changed to the new UID in each of those tables. Also, the variable "anonymous_coward_uid" in the vars table is updated to the new UID.

  • If you chose to delete the new admin user account created by install-slashsite, it is deleted from each of the users* tables. If you choose not to, then UID 2 will not be copied from the 1.0 database; however, all stories, comments, etc. assigned to UID 2 will still be copied.

    We do not bother deleting comments and stories, because those will be overwritten later.

  • For the following tables, the contents are copied directly from the 1.0 database to the 2.0 database:

    abusers content_filters discussions pollanswers
    pollquestions sections storiestuff topics
  • The tzcodes table is copied over directly, after converting the column name "offset" to "off_set", and upper-casing the "tz" column data.

  • For the following tables, the data is copied directly, excluding UID -1 (old AC) and whatever the new AC UID is, and changing seclev to be 1 (where it was 0), changing tzcode to be upper case, and encrypting the passwd:

    users users_comments users_index users_info users_prefs
  • Data is taken from the old users_key field and copied into the new users_param field.

  • For the following tables, the data is copied directly, after changing UID -1 to be whatever the new AC UID is.

    comments submissions accesslog formkeys metamodlog
    moderatorlog pollvoters
  • As mentioned above, the authors table no longer exists, having been rolled into the new users table.

    Authors are selected from the old database, and matched to UIDs from the new database. Then for each UID, the seclev is changed to the proper value, and the lasttitle, section, and deletedsubmissions columns are taken from the old authors table and added to the new users_param table. Also, a flag of "author" with value of "1" is added to the users_param table for that UID.

    A hash of author -> uid is created and saved for use in the next step.

  • For the following tables, the column "aid" is replaced by the column "uid", and the value is changed from the old author's AID to their UID:

    stories sessions
  • If there are any stories that have a NULL UID, the program asks for a UID to assign to the orphaned stories, printing a list of available authors.

  • The newstories table is populated using the data from the stories table.

  • The blocks table is copied over, excluding the blocks that were converted to templates (like header, footer, etc.). Note that any blocks that are now templates, that were customized in the 1.0 site, need to be re-customized in the 2.0 site.

    The "aid" and "blockbak" columns are skipped.

    The skipped blocks, that are now templates, are:

    admin_footer admin_header comment commentswarning
    edit_filter emailsponsor fancybox footer header
    index index2 light_comment light_fancybox
    light_footer light_header light_index light_story
    light_story_link light_story_trailer light_titlebar
    list_filters_footer list_filters_header mainmenu
    menu motd newusermsg organisation pollitem
    portalmap postvote story story_link story_trailer
    storymore submit_after submit_before titlebar

    Also, the "userlogin" block is skipped. It is still in the Slash 2.0 database as a block _and_ a template, and as such the block is not copied from 1.0 to 2.0, since it has changed substantially. See the code for details.

    The colors blocks are fixed; there were previously eight colors per block, now there are ten. The additional colors ($fg[4] and $bg[4]) are both "#CCCCCC". This is done for the "colors" block and any block ending in "_colors".

    The backup_blocks table is populated from the blocks table.

  • The data from the Slash 1.0 sectionblocks table, which does not exist in Slash 2.0, is copied to the blocks table.

  • Selected variables from slashdotrc.pl are copied to the vars table of the Slash 2.0 database. These are:

    mailfrom siteadmin siteadmin_name smtp_server
    sitename slogan mainfontface updatemin
    archive_delay submiss_ts articles_only
    allow_anonymous use_dept max_depth
    defaultsection http_proxy fancyboxwidth
    story_expire titlebar_width run_ads
    authors_unlimited m2_comments m2_maxunfair
    m2_toomanyunfair m2_bonus m2_penalty
    m2_userpercentage comment_minscore
    comment_maxscore submission_bonus goodkarma
    badkarma maxkarma metamod_sum maxtokens
    tokensperpoint maxpoints stir tokenspercomment
    down_moderations post_limit max_posts_allowed
    max_submissions_allowed submission_speed_limit
    formkey_timeframe m2_mincheck m2_maxbonus

    Any values you don't want copied, or want to be additionally copied, can be taken care of either by hand, or by editing the source of this program.

  • The existing values from the 1.0 database vars table are copied to the 2.0 database.

VERSION

$Id$