Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml,v diff -u -r1.28 -r1.29 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml 24 Jun 2004 05:35:18 -0000 1.28 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml 14 Jul 2004 22:02:18 -0000 1.29 @@ -270,7 +270,7 @@ - Upgrading 5.0.0 to 5.0.x or 5.1.x + Upgrading an OpenACS 5.0.0 or greater installation @@ -322,8 +322,33 @@ Upgrading the OpenACS files - OpenACS is distributed as a collection of files, available as one big tarball, via CVS, and via automatic download from within the APM. Upgrades work by first changing the file system (via any of the previous methods), and then using the APM to scan the file system, find upgrade scripts, and execute them. This section describes how to upgrade the file system. Starting with OpenACS 5.0, this section can generally be skipped because the OpenACS APM can directly download new files from the openacs.org repository. - Many OpenACS site developers operate their own CVS repository to keep track of changes from the release OpenACS code. This part describes how to import the latest OpenACS version into your own repository. If you are using CVS, you will unpack the OpenACS 5.1 tarball into a working directory and then import that directory into cvs. If you have changed files in the core packages, cvs will attempt to merge your changes. You may have to manually merge some conflicts. When that's finished, you can update your normal development checkout directory and the new files will appear. If you aren't using CVS, you can unpack the tarball on top of your existing tree, but any customizations you've made to the kernel or core packages will be erased. + + + Chosing a Method to Upgrade your Files + OpenACS is distributed in many different ways: + + as a collection of files + as one big tarball + via CVS + via automatic download from within the APM + (package manager) + + + + Upgrades work by first changing the file system (via any + of the previous methods), and then using the APM to scan the + file system, find upgrade scripts, and execute them. Starting + with OpenACS 5.0, the last method was added, which + automatically changes the file system for you. If you are + using the last method, you can skip this page. This page + describes whether or not you need to be upgrading using this + page or not: + + + + + + Methods of upgrading OpenACS files @@ -346,6 +371,9 @@ Upgrading files for a site in a private CVS repository + + Many OpenACS site developers operate their own CVS repository to keep track of changes from the release OpenACS code. This part describes how to import the latest OpenACS version into your own repository. If you are using CVS, you will unpack the OpenACS 5.1 tarball into a working directory and then import that directory into cvs. If you have changed files in the core packages, cvs will attempt to merge your changes. You may have to manually merge some conflicts. When that's finished, you can update your normal development checkout directory and the new files will appear. If you aren't using CVS, you can unpack the tarball on top of your existing tree, but any customizations you've made to the kernel or core packages will be erased. +
Upgrading a local CVS repository @@ -358,7 +386,12 @@ Step 1: Import new CVS code - There are two common ways to get new OpenACS code into your local CVS repository - via tarball or with a working CVS checkout of OpenACS. Both methods work well for starting your local repository; the second method is better for incremental additions or upgrades. + There are two common ways to get new OpenACS + code into your local CVS repository - via tarball (a) + OR with a working CVS checkout (b) of OpenACS. Both + methods work well for starting your local repository; + the second method is better for incremental additions + or upgrades. @@ -374,7 +407,16 @@ (b): via cvs working checkout - Create a CVS checkout from OpenACS. The first time you do this, you will need to create the checkout directory. We use one dedicated directory for each branch of OpenACS - if you are using OpenACS 5.0,x, you only need an OpenACS 5.0 branch. The openacs-5-1-compat tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package, including .LRN. Each minor release of OpenACS since 5.0 has this tagging structure. For example, OpenACS 5.1.x has openacs-5-1-compat. + Create a CVS checkout from OpenACS. The + first time you do this, you will need to create + the checkout directory. We use one dedicated + directory for each branch of OpenACS - if you are + using OpenACS 5.0,x, you will need a 5.0 + checkout. That will be good for 5.0, 5.01, 5.02, + and so on. But when you want to upgrade to OpenACS + 5.1, you'll need to check out another branch. + + The openacs-5-1-compat tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package, including .LRN. Each minor release of OpenACS since 5.0 has this tagging structure. For example, OpenACS 5.1.x has openacs-5-1-compat. You will want to separately check out all the packages you are using. @@ -386,7 +428,7 @@ [$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@openacs.org:/cvsroot checkout -r openacs-5-1-compat packagename packagename2... [$OPENACS_SERVICE_NAME aolserver]$ cd ../.. [$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1 - If this checkout already exists, you can simply update it instead of recreating it. + If you already have a CVS working checkout, you can simply update it instead of recreating it. [root root]# su - $OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1 [$OPENACS_SERVICE_NAME aolserver]$ cvs up -Pd @@ -421,22 +463,33 @@ [$OPENACS_SERVICE_NAME myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" $OPENACS_SERVICE_NAME/packages/myfirstpackage OpenACS openacs-5-1 - Create a new directory as temporary working space to reconcile conflicts between the new files and your current work. The example uses the cvs keyword yesterday, making the assumption that you haven't checked in new code to your local tree in the last day. + Create a new directory as temporary working space to + reconcile conflicts between the new files and your current + work. The example uses the cvs keyword yesterday, making + the assumption that you haven't checked in new code to + your local tree in the last day. This section should be + improved to use tags instead of the keyword yesterday! [$OPENACS_SERVICE_NAME openacs-5.1]$ cd /var/lib/aolserver [$OPENACS_SERVICE_NAME tmp]$ mkdir $OPENACS_SERVICE_NAME-upgrade -[$OPENACS_SERVICE_NAME tmp]$ cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS -kk $OPENACS_SERVICE_NAME > cvs.txt 2>&1 +[$OPENACS_SERVICE_NAME tmp]$ cvs checkout -d $OPENACS_SERVICE_NAME-upgrade -jOpenACS:yesterday -jOpenACS -kk $OPENACS_SERVICE_NAME > cvs.txt 2>&1 (CVS feedback here) - The file /tmp/openacs-upgrade/cvs.txt contains the results of the upgrade. If you changed files that are part of the OpenACS tarball and those changes conflict, you'll have to manually reconcile them. Use the emacs command M-x sort-lines and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines. When you're finished, or if there aren't any conflicts, save and exit. + The file /tmp/openacs-upgrade/cvs.txt contains the + results of the upgrade. If you changed files that are + part of the OpenACS tarball and those changes conflict, + you'll have to manually reconcile them. Use the emacs + command M-x sort-lines + (you may have to click Ctrl-space at the beginning of the + file, and go to the end, and then try M-x sort-lines) and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines. When you're finished, or if there aren't any conflicts, save and exit. Once you've fixed any conflicts, commit the new code to your local tree. - [$OPENACS_SERVICE_NAME tmp]$ cd openacs-upgrade -[$OPENACS_SERVICE_NAME openacs-upgrade]$ cvs commit -m "Upgraded to 5.1" + [$OPENACS_SERVICE_NAME tmp]$ cd $OPENACS_SERVICE_NAME-upgrade +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cvs commit -m "Upgraded to 5.1" Step 3: Upgrade your local staging site Update your working tree with the new files. The CVS flags ensure that new directories are created and pruned directories destroyed. -[$OPENACS_SERVICE_NAME openacs-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd (CVS feedback) [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit @@ -456,6 +509,7 @@ [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ + Upgrading a Production Site Safely If you are upgrading a production OpenACS site which is on a private CVS tree, this process lets you do the upgrade without risking extended downtime or an unusable site: