[tei-council] Commits, builds, errors and Jenkins

[Martin Holmes]

Hi all,

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:

When Jenkins is already engaged in doing a build, it will not start 
another one until the current one is finished. When the current build 
does finish, 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.

What this means in practice is that, if there are many of us 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.

I put all the above into a blog post here in case it's useful:

<http://hcmc.uvic.ca/blogs/index.php?blog=15&p=8102>

Cheers,
Martin
-- 
Martin Holmes
University of Victoria Humanities Computing and Media Centre
(mholmes at uvic.ca)