README.7continuous

(This file was generated by makeinfo and splitinfo.gawk.)
(Released under the old-style GNU documentation license;
 see sources or other output files for full text.)

9 Continuous integration
************************

The TeX Live sources are subjected to continuous integration testing on
Travis-CI (<https://travis-ci.org/TeX-Live/texlive-source>) via a
git-svn mirror of the sources that is pushed to Github
(<https://github.com/TeX-Live/texlive-source>).  The git-svn mirror is
updated (currently) at 30 minute intervals, and only the last commit
pushed is tested on Travis-CI.

9.1 Transfer from Subversion to Github
======================================

The git-svn program (<https://git-scm.com/docs/git-svn>) is used to
check out the subtree 'Build/source' of the canonical Subversion
repository.  The author index file used is not maintained in either Git
or Subversion but can be provided on request.

   The initial checkout was done by invoking
     git svn --authors-file usermap clone \
       svn://USER@tug.org/texlive/trunk/Build/source

where the 'usermap' file maps Subversion user names to name and emails
of the authors.  Anonymous checkout is also possible:
     git svn --authors-file usermap clone \
       svn://tug.org/texlive/trunk/Build/source

   In the following, we will use _admin_ to refer to a user who has
read/write access to the TeX Live subversion repository, and is also an
administrator of the ''TeX-Live'' team at Github.  The above initial
checkout has been carried out by _admin_ on the server 'texlive.info'.

   On Github, a new git repository named 'texlive-source' was created by
_admin_ within the 'TeX-Live' "organization"
(<https://github.com/TeX-Live>).  The remote was added to the checkout
with 'git remote add origin git@github.com:TeX-Live/texlive-source.git'.

   To automate the update on Github, a new ssh key was generated and
added to the 'texlive-source' repository on Github as deployment key.
Thus, pushes using this key can only go to the 'texlive-source'
repository and not anywhere else.

   The usage of 'git-svn' requires a strict discipline to keep a linear
history in the master branch.  Since we are aiming at a pure mirror
facility on Github, we have decided to further restrict the 'master'
branch of the 'texlive-source' repository on Github to changes by
_admin_.

   This setup allows other developers to branch off 'master' and push
their branches to the Github repository, but all updates need to come
from the local 'master' (not the one on Github) to Subversion, back to
'master' on 'texlive.info', and from there to Github.

9.2 Automatic update of the Git mirror
======================================

_admin_ has installed a cron job on 'texlive.info' running every 30
minute which essentially runs 'git svn rebase' and 'git push' in the
'master' branch of the checkout.  The first command fetches the changes
from the Subversion repository and updates the 'master' branch with
them, and the second pushes changes (if any) to Github.

9.3 CI testing on Travis-CI
===========================

The 'source' tree of TeX Live contains a top-level file '.travis.yml'
which controls the automatic testing on Travis-CI. _admin_ has
registered with Travis-CI and allowed access to the Github's 'TeX-Live'
organization's 'texlive-source' repository.  The default settings are to
build the last commit of each push.  No further action is necessary on
Travis-CI.

   If changes have been pushed via the cron job above, Travis-CI will
automatically checkout the last pushed commit and try building it.

9.4 Releases on Github
======================

Given a git checkout of 'texlive-source':

     git pull
     git tag build-svnNNNN
     git push --tags

and the result will appear at
<https://github.com/TeX-Live/texlive-source/releases>.  Releases can
also be made manually from that web page (see 'tl-update-bindir' for
hints).