releasing-openacs.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?xml version='1.0' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "variables.ent">
%myvars;
]>
<chapter id="releasing-openacs">
<title>Releasing OpenACS</title>
<section id="releasing-openacs-core">
<title>OpenACS Core and .LRN</title>
<orderedlist>
<listitem>
<formalpara>
<title>Update Translations</title>
<para><xref linkend="update-translations"/></para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Rebuild the Changelog</title>
<para>Rebuild the Changelog. I use a tool called cvs2cl. Run this command from the package root to automatically generate a Changelog file in the same dir. We generate two changelogs, one for the minor branch and one for the most recent release. The example below is for OpenACS 5.0.2:</para>
</formalpara>
<screen><action>cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
cvs2cl -F <replaceable>oacs-5-0</replaceable> --delta <replaceable>openacs-5-0-0-final</replaceable>:<replaceable>oacs-5-0</replaceable> -f ChangeLog
cvs2cl -F <replaceable>oacs-5-0</replaceable> --delta <replaceable>openacs-5-0-1-final</replaceable>:<replaceable>oacs-5-0</replaceable> -f ChangeLog-recent</action></screen>
</listitem>
<listitem>
<formalpara>
<title>Update Version Numbers</title>
<para>The version numbers in the documentation and in the packages must be updated. This should only happen after a release candidate is approved.</para>
</formalpara>
<remark>.LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in OpenACS cvs tree). My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and <link linkend="releasing-package">release those packages</link> when they change. This model is already broken because following it means that dotlrn-prereqs don't get new translations.</remark>
<orderedlist>
<listitem>
<para>Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number.
</para>
</listitem>
<listitem>
<para>Add new section in /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml
</para>
</listitem>
<listitem>
<para>Regenerate all HTML docs</para>
<screen>cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml
make</screen>
</listitem>
<listitem>
<para>Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/readme.txt with the new version number</para>
</listitem>
<listitem>
<para>Update version number and release date in all of the
core packages. Use
/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/update-info.sh
with the new version number and the release date as arguments.
Run it from /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages:</para>
<screen>cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages
./acs-core-docs/www/files/update-info <replaceable>5.2.1</replaceable> <replaceable>2006-01-16</replaceable></screen>
</listitem>
<listitem>
<para>Install a new site using the modified code and verify that the automated tests pass.</para>
</listitem>
<listitem>
<para>Commit changes to CVS</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<formalpara>
<title>Tag the files in CVS</title>
<para>The steps to this point should have ensured that the head of the current branch contains the full set of code to release. Now we need to tag it as the code to be released.</para>
</formalpara>
<orderedlist>
<listitem>
<para>Check out OpenACS Core. The files must be checked
out through a cvs account with write access and should be a
checkout from the release branch. In this example, we are assuming
this is being done as a local user on openacs.org (which make the
checkout and tagging operations much faster).</para>
<screen><action>cd /var/tmp
cvs -d /cvsroot checkout -r <replaceable>oacs-5-0</replaceable> acs-core</action></screen>
<para>If doing .LRN, repeat with the dotlrn cvs tree.</para>
<screen><action>cd /var/tmp
mkdir dotlrn-packages
cd dotlrn-packages
cvs -d /dotlrn-cvsroot checkout -r <replaceable>dotlrn-2-0</replaceable> dotlrn-all
</action></screen>
</listitem>
<listitem>
<para>Tag the tree. If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag. (Ie, if releasing 5.0.3 final, move the openacs-5-0-compat flag.)</para>
<screen><action>cd /var/tmp/openacs-4
cvs tag -F <replaceable>openacs-5-0-0a1</replaceable>
cvs tag -F <replaceable>openacs-5-0-compat</replaceable>
</action></screen>
<tip>
<title>Branching</title>
<para>When we feature-freeze on HEAD as part of the release process, we are blocking new development. To avoid this, we branch the code at this point, so that new work can continue on HEAD while the branch is stabilized for release. However, branching means that bug fixes have to be synchronized between HEAD and the branch, and bug fixes tend to be more frequent right at this time. Therefore, our actual branch point is as late as possible - essentially, we do not branch until and unless new feature work is actively blocked by the feature freeze. Branching is almost the same as tagging, except for the flag and slightly different tag nomenclature. To see the list of old branches, <computeroutput>cvs status -v somefile</computeroutput>.</para>
<screen>cvs tag -b <replaceable>oacs-5-0</replaceable></screen>
</tip>
<para>If doing .LRN: Since the .LRN packages aren't all in one
module, we iterate through all of the modules. Log in first
(cvs login) so that you don't have to log in for each
module.</para>
<screen><action>cd /var/tmp/dotlrn-packages
for dir in *; do ( cd $dir && cvs tag <replaceable>dotlrn-2-0-2-final</replaceable> ); done
for dir in *; do ( cd $dir && cvs tag -F <replaceable>openacs-5-0-compat</replaceable> ); done
</action></screen>
<para>Note that for the compat tag we use the <action>-F</action> flag which will force the tag to the new version (just in
case someone has created the tag already on another version). Exercise care when doing this since
you don't want to inadvertently move a prior release tag. Also if the tagging goes horribly wrong
for some reason you can delete the tag via <command>cvs tag -d <symbolic_tag></command>.</para>
</listitem>
<listitem>
<para>Apply the <computeroutput>final</computeroutput> tag across the tree. First, check out the entire OpenACS tree, getting the most recent stable version of each package. This is most simply done on openacs.org:</para>
<screen><action>cd /var/tmp
cvs -d /cvsroot checkout -r <replaceable>openacs-5-1-compat</replaceable> openacs-4
cd openacs-4
cvs tag <replaceable>openacs-5-1-2-final</replaceable></action></screen>
</listitem>
</orderedlist>
</listitem>
<listitem>
<formalpara>
<title>Make the tarball(s)</title>
<para></para>
</formalpara>
<itemizedlist>
<listitem>
<formalpara>
<title>openacs-core</title>
<para></para>
</formalpara>
<orderedlist>
<listitem>
<para>Go to a new working space and export the tagged files.</para>
<screen><action>mkdir /var/tmp/tarball
cd /var/tmp/tarball
cvs -d /cvsroot export -r <replaceable>openacs-5-0-0a1</replaceable> acs-core</action></screen>
</listitem>
<listitem>
<para>Generate the tarball.</para>
<screen><action>cd /var/tmp/tarball
mv openacs-4 openacs-<replaceable>5.0.0a1</replaceable>
tar cz -f <replaceable>openacs-5.0.0a1.tar.gz</replaceable> openacs-<replaceable>5.0.0a1</replaceable>
</action></screen>
</listitem>
</orderedlist>
</listitem>
<listitem>
<formalpara>
<title>dotlrn</title>
<para></para>
</formalpara>
<orderedlist>
<listitem>
<para>Go to a new working space and export the tagged
files. (was getting errors here trying to use -d, so
gave up and just moved things from openacs-4 to
OpenACS at the end)</para>
<screen><action>mkdir /var/tmp/dotlrn-tarball
cd /var/tmp/dotlrn-tarball
cvs -d /cvsroot export -r <replaceable>openacs-5-0-0a1</replaceable> acs-core
cd /var/tmp/dotlrn-tarball/openacs-4/packages
cvs -d /cvsroot export -r <replaceable>openacs-5-0-0a1</replaceable> dotlrn-prereq
cvs -d /dotlrn-cvsroot export -r <replaceable>dotlrn-2-0-0a1</replaceable> dotlrn-core
</action></screen>
</listitem>
<listitem>
<para>Copy the dotlrn install.xml file, which controls
which packages are installed on setup, to the root
location:</para>
<screen><action>cp /var/tmp/dotlrn-tarball/openacs-4/packages/dotlrn/install.xml \
/var/tmp/dotlrn-tarball/openacs-4
</action></screen>
</listitem>
<listitem>
<para>Generate the tarball</para>
<screen><action>cd /var/tmp/dotlrn-tarball
mv openacs-4 dotlrn-<replaceable>2.0.0a1</replaceable>
tar cz -f <replaceable>dotlrn-2.0.0a1.tar.gz</replaceable> dotlrn-<replaceable>2.0.0a1</replaceable>
</action></screen>
</listitem>
</orderedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<formalpara>
<title>Test the new tarball(s)</title>
<para>Download the tarballs just created and install them and make sure everything looks okay and that automated tests pass.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Update Web site</title>
<para>Update the different places on OpenACS.org where we track status.</para>
</formalpara>
<itemizedlist>
<listitem><para>Release Status for the current version - something like http://openacs.org/projects/openacs/5.0/milestones</para>
</listitem>
<listitem>
<para>Home page of openacs.org</para>
</listitem>
<listitem>
<para>Post a new news item</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<formalpara>
<title>Clean Up</title>
<para>Clean up after yourself.</para>
</formalpara>
<screen><action>cd /var/tmp
rm -rf tarball dotlrn-tarball dotlrn-packages openacs-<replaceable>5.0.0a1</replaceable>
rm -rf /var/tmp/openacs-4</action></screen>
</listitem>
</orderedlist>
<para>
Here is a shell script that automates packaging the tarball (it's a bit out of date with the new steps - I've been doing everything manually or with little throwaway scripts as detailed above until the process is stabilized).
</para>
<programlisting><xi:include href="../../../../etc/install/build-release.sh" xi:parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback>release script missing</xi:fallback></xi:include></programlisting>
<para><phrase role="cvstag">($Id: releasing-openacs.xml,v 1.24.2.1 2020/07/02 08:39:25 gustafn Exp $)</phrase></para>
</section>
<section id="update-repository">
<title>How to Update the OpenACS.org repository</title>
<orderedlist>
<listitem>
<para>
Setup a local OpenACS server running 5.0 or better.
</para>
</listitem>
<listitem>
<para>
Edit <computeroutput>packages/acs-admin/www/apm/build-repository.tcl</computeroutput> and adjust the Configuration Settings. </para>
</listitem>
<listitem>
<para>
Request /acs-admin/apm/build-repository on your new server.
</para>
</listitem>
<listitem>
<orderedlist>
<listitem>
<para>
The page will find all branches in the cvs repository labeled oacs-x-y, and build a repository channel for each of
those branches where x>=5 (so not for 4.6 and earlier). It will also build a channel for HEAD,
which will be named after what you set in 'head_channel' above.
</para>
</listitem>
<listitem>
<para>
For each channel, it'll do an anonymous checkout of packages and contrib/packages, then build .apm files for each package in the checkout.
</para>
</listitem>
<listitem>
<para>
The files will be stored on the server's hard drive in the directory specified by the 'repository_dir' variable in the page script, by default "$::acs::rootdir/www/repository/".
</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>
If you're on openacs.org, everything should now be fine. Otherwise, you need to move the entire directory tree to openacs.org:/web/openacs/www/repository, replacing what was already there.
</para>
<para>This is automated on OpenACS.org by having a dedicated site just for building the repository, invoked with this shell script. Since the page circumvents security checks for ease of use, the entire site is limited to local requests. The script is called daily with a cron job.</para>
<programlisting>#!/bin/sh
#set -x
STATUS=`wget --output-document - http://127.0.0.1:8002/build-repository.tcl | grep DONE | wc -l`
if [ $STATUS -eq "1" ]
then
rm -rf /web/openacs.org/www/repository.old
mv /web/openacs.org/www/repository /web/openacs.org/www/repository.old
cp -r /web/repository/www/repository /web/openacs.org/www/repository
fi</programlisting>
</listitem>
</orderedlist>
</section>
<section id="releasing-package">
<title>How to package and release an OpenACS Package</title>
<para>In this example, we are packaging and releasing <computeroutput>myfirstpackage</computeroutput> as version 1.0.0, which is compatible with OpenACS 5.0.x.</para>
<orderedlist>
<listitem>
<para>Update the version number, release date, and <ulink url="http://openacs.org/forums/message-view?message_id=161393">package maturity</ulink> of your package in the <ulink url="/acs-admin/apm/">APM</ulink>.</para>
</listitem>
<listitem>
<para>Make sure all changes are committed.</para>
</listitem>
<listitem>
<para>Tag the updated work.:</para>
<screen><action>cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/<replaceable>myfirstpackage</replaceable>
cvs tag <replaceable>myfirstpackages-1-0-0-final</replaceable>
cvs tag -F <replaceable>openacs-5-0-compat</replaceable>
</action></screen>
</listitem>
</orderedlist>
<para>Done. The package will be added to the <ulink url="http://openacs.org/repository">repository</ulink> automatically. If the correct version does not show up within 24 hours, ask for help on the OpenACS.org development forum.</para>
</section>
<section id="update-translations">
<title>How to Update the translations</title>
<orderedlist>
<listitem>
<para>Identify any new locales that have been created.
For each new locale, check the parameters, especially that
the locale is in the format <emphasis>[two-letter code for
language, lowercase]_[TWO-LETTER CODE FOR COUNTRY,
UPPER-CASE]</emphasis>, and create a sql command. A
example sql command for creating a locale is:</para>
<programlisting>insert into ad_locales
(locale, label, language, country, nls_language, nls_territory,
nls_charset, mime_charset, default_p, enabled_p)
values ('fa_IR', 'Farsi (IR)', 'fa', 'IR', 'FARSI', 'IRAN', 'AL24UTFFSS',
'windows-1256', 't', 'f');</programlisting>
<para>Put this command into the following four files. For the
upgrade files, the correct filename will depend on the
exact version.</para>
<itemizedlist>
<listitem>
<para><computeroutput>/packages/acs-lang/sql/postgresql/ad-locales.sql</computeroutput></para>
</listitem>
<listitem>
<para><computeroutput>/packages/acs-lang/sql/postgresql/upgrade/upgrade-<replaceable>current-version</replaceable>.sql</computeroutput></para>
</listitem>
<listitem>
<para><computeroutput>/packages/acs-lang/sql/oracle/ad-locales.sql</computeroutput></para>
</listitem>
<listitem>
<para><computeroutput>/packages/acs-lang/sql/oracle/upgrade/upgrade-<replaceable>current-version</replaceable>.sql</computeroutput></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Make a backup of the production database. Restore it as a new database. For example, if upgrading from OpenACS 5.1.1, and the site name/database name is translate-511, create translate-512b1.</para>
</listitem>
<listitem>
<para>Check out the latest code on the release branch (e.g., oacs-5-1) as a new site, using the new site name (e.g., /var/lib/aolserver/translate-512b1. Copy over any local settings - usually, <computeroutput>/etc/config.tcl</computeroutput> and <computeroutput>/etc/daemontools/run</computeroutput> and modify appropriately. Also, copy over several translation-server-only files:
<programlisting>...TBD
</programlisting>
</para>
</listitem>
<listitem>
<para>Shut down the production site and put up a notice (no procedure on how to do this yet.)</para>
</listitem>
<listitem>
<para>Start the new site, and upgrade it.</para>
</listitem>
<listitem>
<para>Go to <ulink url="/acs-lang/admin">ACS Lang admin page</ulink> and click "Import All Messages"</para>
</listitem>
<listitem>
<para>Resolve conflicts, if any, on the provided page.
</para>
</listitem>
<listitem>
<para>Back on the admin page, click the export link. If there are conflicts, the messages will be exported anyway and any errors will be shown in the web interface.</para>
</listitem>
<listitem>
<para>Commit the message catalogs to cvs.</para>
</listitem>
<listitem>
<para>From the packages dir, run the acs-lang/bin/check-catalog.sh script. (This checks for keys no longer in use and some other things. Until it is rolled into the UI, do it manually and check the results and take whatever steps you can intuit you should do.)
</para>
</listitem>
<listitem>
<para>CVS commit the catalog files. Done</para>
</listitem>
<listitem>
<para>If everything went well, reconfigure the new site to take over the role of the old site (<computeroutput>/etc/config.tcl</computeroutput> and <computeroutput>/etc/daemontools/run</computeroutput>). Otherwise, bring the old site back up while investigating problems, and then repeat.
</para>
</listitem>
</orderedlist>
</section>
</chapter>
