In order for the APM to notice that there is a new upgrade script available, we need to keep the version-number in the
.info files up-to-date.
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:
- 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
- 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)
- 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.
- 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
This is, at least, how I think things should work. Please let me know if I'm mistaken 😊
