Documenting TEI SVN editing/building
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.