Forum OpenACS Development: Naming Conventions for sql upgrade scripts

Collapse
1: Naming Conventions for sql upgrade scripts
Posted by Joel Aufrecht on 02/26/04 09:47 AM
I'm responding to an email question in the forums for broader audience:

<blockquote> Outlier #1:  The upgrade script should be run by anyone running on a
previous tagged version (e.g. rc2, rc1, 1.x).  I called the script
"upgrade-feb-20-2004.sql", consistent with the naming scheme for other
upgrade scripts in the sql/dbname/upgrade subdirectory.  I haven't
checked to see if APM will pick up and run it correctly.  Joel, if you
happen to know the answer, and that it *should* work, maybe we're
really actually truly ready!  😊
</blockquote>

Our release numbering rules are here:
https://openacs.org/doc/openacs-HEAD/eng-standards-versioning.html

The APM's documentation is here: https://openacs.org/doc/openacs-HEAD/apm-design.html

Useful facts that I can't find in the documentation:

The APM decides which scripts to run based on the version number in the .info file.  So if you add an upgrade script, you must change the version number in the .info to an equal or higher value.

Example: foo package is at 5.0.3a1
You need to add an upgrade script.  Call it
/sql/postgresql/upgrade-5.0.3a1-5.0.3a2.sql

and change the version in foo.info to 5.0.3a2.

Later, the package is released, so the version number in foo.info is changed to 5.0.3.  Anyone upgrading from 5.0.2 to 5.0.3 will have the script run automatically.

Using any letter besides d, a, or b for revision causes problems - both in the .info and in the upgrade version numbers.  'rc' is not yet supported - instead just keep using b numbers.  So if RC1 comes after beta 4, and we need to make more changes, we go to b5, b6, etc.

Collapse
2: Re: Naming Conventions for sql upgrade scripts (response to 1)
Posted by Andrew Grumet on 02/26/04 02:39 PM
Okay so the older, 1.0 era upgrade scripts in that directory are also incorrectly named.  Ugh.

As for mine, the task now is to get the version numbers straight and make sure the .info file is set correctly for release.

I understand that we are getting ready to cut version "2.0", so the new file name should be something like

/sql/postgresql/upgrade/upgrade-2.0xxx-2.0.sql

Okay, so the question is, what is "xxx" above.

The dotlrn.info file at the head of the dotlrn-2-0 branch says "2.0a3".  The latest tarball available at https://openacs.org/projects/dotlrn/download/ is "2.0.0rc1".  The CVS tree has many other tags including one for "rc2".

If we want to keep APM happy, we should use the value from the .info file.  So...

/sql/postgresql/upgrade/upgrade-2.0a3-2.0.sql

Any objection?

Collapse
3: Re: Naming Conventions for sql upgrade scripts (response to 2)
Posted by Joel Aufrecht on 02/26/04 04:01 PM
What if we find a new bug that requires another upgrade script?

I think the better practice is to never end an upgrade script with the release version; instead just use b# until infinity.    The underlying principle is that the author of the code never gets to say that it's release-worthy - that's the job of Quality Control.  So the author can only pump out release candidates; eventually the accepted release candidate becomes the release.  But the only renumbering that happens then is in the docs and .info files, which the release manager handles.

But this practice isn't followed by most of the scripts, so ....

Collapse
5: Re: Naming Conventions for sql upgrade scripts (response to 3)
Posted by Andrei Popov on 02/28/04 01:48 PM 
> I think the better practice is to never end an
> upgrade script with the release version; instead
> just use b# until infinity.

...or add a fourth sequential numeral in version number like:

	foo-5.0.3.12345

that would indicate patch/upgrade level. To make it more explicit, it can be separated with an underscore or a hyphen instead of a dot.

Yet another alternative is indeed to use datestamps, but then an 8-char CCYYMMDD format should be used (ensure proper sorting and is Y2K compliant :)

Collapse
4: Re: Naming Conventions for sql upgrade scripts (response to 1)
Posted by Andrew Grumet on 02/27/04 03:58 PM
Makes sense to me.
Collapse
6: Re: Naming Conventions for sql upgrade scripts (response to 1)
Posted by Andrew Grumet on 03/01/04 04:09 PM
I have verified that APM does not recognize the "upgrade-feb-20-2004.sql" name originally used.  I will rename the file to work correctly with APM.