Academic

I made my first few commits today, and I thought I'd report my experiences in case they help anyone else who's intending to do this but hasn't tried yet. This is all on Ubuntu Linux.

First I followed these instructions to install the TEI packages for Debian on my machine:

http://wiki.tei-c.org/index.php/TEIDebian

I made a directory and checked out the full source my local machine:

mkdir sf_repo
svn co https://tei.svn.sourceforge.net/svnroot/tei sv_repo

Then I moved to the P5 directory and ran a build using "make":

cd sf_repo/trunk/P5
make

This took a long while the first time, and showed me lots of messages that turned out to be a mixture of the incomprehensible, the ignorable, and the relevant. Relevant messages (for me) are ones that I can imagine a way to fix; or that were caused by one of my changes (this hasn't happened yet).

I soon realized that watching the messages go by in my terminal was not really useful, so I started saving the error output to a separate file incorporating a datetime stamp in its name every time I ran a build. This is how I'm working now:

#Go to the root directory of the SVN tree
cd sf_repo

#Check out the latest changes
svn up

#Go into the P5 directory
cd trunk/P5

#Run a preliminary build
make 2> /path/to/error/file/make_errors_`date +"%Y-%m-%dT%H:%M:%S"`.txt

#Make my own changes...

#then run another build
make 2> /path/to/error/file/make_errors_`date +"%Y-%m-%dT%H:%M:%S"`.txt

#Finally, diff the two latest error files to see if I've fixed 
#any previous errors, or introduced any new ones. For this I 
#use Meld.

#Commit my changes if all is OK
cd Source/Specs #(for instance, assuming that's where I edited a file)
svn commit -m "Message explaining my changes."

#Go to Jenkins and watch it build the changed source, 
#then check for errors again.

Watching Jenkins today answered a number of questions for me about how it works, especially with regard to queueing up builds:

Jenkins seems to be configured to run up to two builds simultaneously. When it is already engaged in doing two builds, it will not start another one until one of the current ones is finished. Then it will initiate a new build which incorporates ALL the changes which have been committed during the time it was engaged in the previous build. What this means is that some revisions are never built independently. For instance, I committed two changes to SVN while a build was in progress (revisions 8816 and 8817); when Jenkins was free, it commenced a build of the documentation that incorporated both those changes, meaning that no independent build of revision 8816 was created. Only revision 8817 was built. (At least, that's my current understanding based on observation.)

What this means in practice is that, if there are many editors making changes and commits, we will only see the results of our commits (in terms of errors and warnings) mixed in with those from other commits which have happened around the same time. That will make it slightly more difficult to tell whether you caused an error or not, and how you might fix it. So I think it's probably even more important to have a local build environment you can use to test your changes before committing them. While errors can easily be undone by means of reverting, there is a danger that in order to do this, you might have to revert past other people's changes that were committed just after your own.

Made two sets of changes to TEI source and committed them today. Watching to see how Jenkins handles the results. The first one went fine, with no errors (as expected from my local tests). Local tests also show no errors from the second batch of changes (relating to nested bibls), but the first Jenkins build has only just started. I took advanted of the second commit being in two different directories to stagger the commits, so that Jenkins will (presumably) start two separate builds; I'm now waiting to see if it does them serially or in parallel. We need to figure this out for our own local copy of Jenkins.

Command-line run from /trunk/P5 to get the errors out to a timed file, for diffing against previous error output:

make 2> /home/mholmes/WorkData/tei/make_errors_`date +"%Y-%m-%dT%H:%M:%S"`.txt

(Just to save me from mistyping and forgetting and having to re-learn.)

Following my own instructions in the previous post, got my working build environment set up on the work computer, and ran a test build. I'm now running another build, saving the output to a file so I can examine the errors coming out of tests.

Follow-up work arising out of the council meeting:

• Set up and tested a working build environment (here documented because I'll have to do it at work too):
  • Setting up repo:

    gpg --keyserver wwwkeys.uk.pgp.net --recv-keys FEA4973F86A9A497
    sudo apt-key add ~/.gnupg/pubring.gpg 

  • Add to /etc/apt/sources.list:

    deb http://tei.oucs.ox.ac.uk/teideb/binary ./
    

  • Installing packages:

    sudo apt-get update
    sudo apt-get install psgml xmlstarlet debiandoc-sgml linuxdoc-sgml jing jing-trang-doc libjing-java rnv texlive-xetex
    sudo apt-get install trang-java tei-p5-doc tei-emacs saxon nxml-mode-tei tei-p5-xsl  tei-p5-xsl2 tei-roma onvdl
    

  • Removing gcj to avoid confusion (advice from here):

    sudo apt-get remove `apt-cache search gcj | grep gcj | awk '{print $1}'`
    

  • Checking out the source (in home dir):

    mkdir tei
    cd tei
    svn co https://tei.svn.sourceforge.net/svnroot/tei .
    

  • Test-build of the source:

    cd trunk/P5
    make
    

    Doing this for the first time, the main build was fine, as were most of the tests, but some tests towards the end threw up errors; I'm not sure yet which of these errors might be significant, and how to find that out or do anything about it.
• Went through the minutes from the meeting and gave a bit of feedback.
• Did some reading around in the source code to prepare for my first edit.
• Posted details of my planned edit on the relevant ticket to get feedback before making any actual changes.

Posting time spent over the weekend on preparation work for the workshop (creation of stage diagrams stepping through various files and processes), editing of existing presentations, and a conference call with SB and DJB.

Meetings before and after lunch.

Prepared a presentation for UBC library folks (meeting this morning) on our XML projects and workflows. Used the opportunity to test LibreOffice; xferred to laptop, which has OpenOffice, and found a problem with fonts when arrows were used. Note to self: dump OpenOffice for LibreOffice everywhere, for better compatibility and stability.