Testing, 1, 2, 3!

The discussions in IRC this morning revolve around release notes and the new XulRunner branch. I’m chiming in to talk about the latter.

This branch needs testing and lots of it. We here at MVLC have been testing it on our development/test servers, even with production data, but we’ve not used it in production nor put it through all of its paces. Specifically, we developers don’t spend a lot of time in cataloging, acquisitions, serials, etc. We’ve kicked the tires, and basic circulation still works. Some of the more advanced features have gotten a workout, but nothing systematic so far.

So, what’s in it for me, you ask? Why should I care about a “new XulRunner branch” and what does that mean for Evergreen?

Glad you asked. The new XulRunner branch updates the compatibility of Evergreen with newer versions of XulRunner, the underlying technology used to create the Evergreen staff client. The staff client is currently only compatible with older, out-of-date versions of XulRunner (1.9.x and 3.6.x). These old versions have some known problems that are fixed in later versions. The new XulRunner branch actually makes the Evergreen staff client compatible with later versions and still maintains compatibility with the older versions of XulRunner. (There is a catch to that compatibility, however. You can’t use different XulRunner versions with the same server because of changes in the OPAC pages. You have to use all the same XulRunner version with all of your clients.)

So, what does using a newer version of XulRunner get you? For starters, the community gets a greater longevity out of the current staff client. This lowers the pressure on the developers to come up with something new. End users will notice an improvement in performance. We’ve not actually measured the difference that using a newer XulRunner makes, but screen refreshes were noticeably faster when using XulRunner 11.0 compared to 1.9. Additionally, the client should freeze up less and use less RAM. Newer XulRunner versions may open possibilities for easier development of new features if we can take advantage of the technologies being added to XulRunner. The list goes on.

I know, I had you at “noticeably faster,” and now you want to know how to install it and try it out. Well, I’m now ready to tell you how, at least if you have a Debian or Ubuntu test server set up. Oh, and don’t worry. If you’ve installed Evergreen from a tarball (.tar.gz file), then you should be able to follow these instructions.

ACHTUNG! MINEN!

DO NOT attempt the following on your production server. You will have a lot of very unhappy users if you do. I assume you have a test server set up with its own test database where you can try the following steps. I also only outline the basic steps needed to install and test the new XulRunner branch. I skip over things like running upgrade scripts on the database if necessary.

CAVEAT LECTOR.

Before you do anything else, you’ll want to make sure that you have some essentials in place. Most of what you need should be available from the last time that you installed Evergreen, but some needed packages may not necessarily be there. To make sure that you have everything, run the following commands as the root user or via sudo:

apt-get install build-essential 
apt-get install git-core 
apt-get install zip 
apt-get install nsis

The above will ensure that you have the GNU autotools package installed as well as any other required modules for building programs from source code that may be missing on a default installation. (Not likely that you’ll be missing any, but it is always good to make sure they are all there.) It also installs the git program that you will need to fetch the latest Evergreen source code, and makes sure that the zip and nsis packages, needed by the client installer, are present.

Next, you’ll want to clone the public repositories onto your server. I usually do this as the opensrf user in the opensrf user’s home directory:

git clone git://git.evergreen-ils.org/Evergreen.git 
cd Evergreen 
git remote add working git://git.evergreen-ils.org/working/Evergreen.git 
git fetch working

The above will clone the Evergreen repository, checkout the master development branch of Evergreen, and make the working repository available to you. You will also have read-only access to the repositories, so there is no worry about messing something up. If you do, you can simply delete your local directory and follow the above steps again, or if you know some more about git, you can fix it yourself. Using these commands, there is absolutely no danger of doing harm to the public repositories, so feel free to experiment.

Now, you’re ready to merge the new XulRunner branch’s code into master. Let’s make a new branch to do the merge in so we don’t mess up the copy of master that was checked out for us automatically:

git checkout -b new_xulrunner origin/master

The above command literally tells git to make a new branch named
“new_xulrunner” that is based on the master branch of the origin
repository and to make that new branch active, which means that you are
now using that new branch. Origin is typically the repository that
you cloned when creating your own local copy, but it can be changed
with the proper commands.

Now, we can merge the new XulRunner branch from the working
repository into our new branch:

git merge working/collab/tsbere/new_xulrunner

Hopefully, that merges cleanly without reporting any conflicts. If that is the case, then you can proceed to the installation of Evergreen according to the instructions in the README file. You will need to run autoreconf -i before you can run configure.

After you’ve done the make install and changed ownership of the /openils directory but before you restart Apache, you will want to build the actual staff client with the following commands, assuming that you are still in your Evergreen clone directory:

cd Open-ILS/xul/staff_client 
make rigbeta 
make rebuild devbuild 
make updates-client

If you don’t do the above as root or with sudo, then it may fail. I always like to change the ownership on my source directory after doing make install when I also change ownership of the /openils directory:

sudo chown -R opensrf:opensrf ./ /openils/

If you do run the commands as root, then you’ll likely need to run
the above chown command again.

Assuming that everything has gone as expected, you can now start your
OpenSRF services and restart Apache. In addition to having a working
Evergreen installation with the new XulRunner branch installed, you
should also have a new URL available on your server where you can
download the new XulRunner client:

http://YOUR_SERVER_NAME/updates/manualupdate.html

You can go there, download the new client, and you should be able to log in to your test server with the new client as usual.

Once you’ve logged in, you should test the functions that you care the most about. You’ll be relieved when you add a bibliographic record, create a new copy, and can circulate it to a patron that you’ve also just added. If you have some existing data and you’ve run the proper upgrade scripts (beyond the scope of this document), then try the new client out with some of your existing work flows. Be sure to report any problems you encounter by adding comments on the Launchpad Bug or by sending an email to the developers' list.