Forum OpenACS Development: UPGRADE Scripts PLEASE

If you want to guarantee that no one upgrades, please continue this practice. If, on the other hand, you want to follow what was set out as before, ADD them. It is not that hard to write a little script to do updates. If something breaks then it still needs to be documented.

It was agreed upon that from the Beta release of 4.5 on ALL data model changes would have a script for upgrade. The APM already has this capability, use it please, so everyone doesn't have to run diff and figure out what changed.

P.S. What a pain in the a$#

Scenario:

Jon's running OpenACS 4.5 which has version 4.0a of the Download package. I decide to add a great new feature to Download which requires a new table. So, I add the new SQL to download-create.sql and then dutifully create an upgrade file - upgrade-4.0a-4.1.sql. I then update the .info file and change the version to 4.1.

Jon does a CVS update and then runs the package installer to see if any of his installed packages have been upgraded. The installer tells him that Download v.4.1 is now available and when Jon selects it, the installer runs the appropriate upgrade script.

Now, let's say that, a couple days later, I decide to add another new SQL feature. Can I add it to that first upgrade script? No! Since Jon's already upgraded, he'll never get it and his install will probably break. So, I guess the rule is: Whenever you commit a change to a datamodel file, upgrade the version in the .info file (eg. 4.1.1) and create a new upgrade file (upgrade-4.1-4.1.1.sql).

Sidetrack: For some reason, the last CVS merge from the 4.5 branch to the HEAD branch didn't merge all the .info files properly. So, a lot of the core package .info files have versions < 4.5 even though they are all = 4.5 in the 4.5 branch. (Confused yet?). In any case, I'm going to go through and fix that now.

What all package developers should do now:

1. Do a 'cvs log' on all the .sql files in your package.

   $ cvs log bookmarks-create.sql
   Working file: bookmarks-create.sql
   head: 1.19
   branch:
   locks: strict
   access list:
   symbolic names:
   	oacs-4-5-final: 1.18
   	oacs-4-5-rc-1: 1.18
   	don-merge-1: 1.18
   

2. Look for the tag "oacs-4-5-final" and compare that to the tag listed next to "head:". If they are the same - you're fine. If not, you need to do a diff between those 2 versions and see what the difference is. (cvs diff -r 1.18 -r 1.19 bookmarks-create.sql)
3. create an upgrade script. The starting version should be the current version of your package (look in the .info file). Choose a new version number. So, for this bookmarks example, it would be upgrade-4.1.1b-4.1.2.sql. Put this file in a separate 'upgrade' directory (i.e. packages/bookmarks/sql/postgresql/upgrade/)

   Repeat steps 1-3 for each SQL file in your package.

4. Go to the APM and upgrade the version on your package. While you're there, update the description, author-contact info and the file-list

tia

I thought there was a doc on versions or at least a mention of it somewhere. We should have a standard on versioning though. The original intent at AD was that the core was released with the same major.minor version, but all the non-core packages could have their own versions. This got screwed up and you get packages like news that are version 4.1b. This says it is version 4.1 beta (the letters are supposed to mean something). In reality this package should be named .1b or 1.0b to more accuratly describe it.

I hope this makes sense and it should be on the development do's and don'ts somewhere.

It turns out the reason is that the APM correctly loads all the upgrade-scripts between two versions, also if there are more than one script.

Unfortunately, it loads them in reverse (or at least not the correct) order, which is what caused a later upgrade script to fail and data to get lost.

I'm looking into fixing it now, but if anybody knows off-hand what the problem is, they can save me a bit of trouble.

I'm trying to find out just what is happening in "apm_data_model_scripts_find" :)

/Lars

"apm_upgrade_script_compare" had two different queries, both of which were named "test", so the query dispatcher happily went and used the same query twice, and "apm_upgrade_script_compare" would always return 1 (for some reason, not sure why 1).

There may be other problems, I don't know.

I'll be committing once I've run a few more tests.

/Lars