start work on CI documentation

1 files changed, 134 insertions, 0 deletions

diff --git a/Build/source/doc/tlbuild.texi b/Build/source/doc/tlbuild.texi
index 3ea08d701b6..062cc1d58b1 100644
--- a/Build/source/doc/tlbuild.texi
+++ b/Build/source/doc/tlbuild.texi
@@ -2653,6 +2653,140 @@ git push --tags
 Releases can also be made manually from that web page (see
 @code{tl-update-bindir} for hints).
 
+@node Continuous Integration
+@chapter Continuous Integration
+
+@cindex ci
+@cindex continuous integration
+
+The sources of @TL{} are subjected to continuous integration testing on
+Travis-CI (@url{https://travis-ci.org/TeX-Live/texlive-source}) via a
+git-svn mirror of the sources that is pushed to Github
+(@url{https://github.com/TeX-Live/texlive-source}). The git-svn mirror
+is updated (currently) at a 30min interval and only the last commit
+pushed is tested on Travis-CI.
+
+@subheading Transfer from Subversion to Github
+
+Git-svn (@url{https://git-scm.com/docs/git-svn}) is used to check out
+the subtree @code{Build/source} of the Subversion repository. The author
+index file used is not maintained in Git or Subversion but provided on
+demand. 
+
+TODO what should we do here with the author index file? It contains a
+mapping from subversion names to name/email as shown in git.
+
+The initial checkout was done by invocing
+@code{git svn --authors-file usermap clone svn://USER@tug.org/texlive/trunk/Build/source}
+where the @code{usermap} file maps subversion user names to name and
+emails of the authors. 
+
+TODO should we use anonymous checkout here? Should be possible!
+
+In the following we will refer with @emph{admin} to a user who has
+read/write access to the \TL{} subversion repository, and an
+administrator of the \@code{TeX-Live} Team on Github. The above initial
+checkout has been carried out by @emph{admin} on the server
+@code{texlive.info}. 
+
+On Github (@url{https://github.com/}) a new git repository named
+@code{texlive-source} was created by @emph{admin} within the
+@code{TeX-Live} organization (@url{https://github.com/TeX-Live/}), the
+remote added to the checkout with
+@code{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 @code{texlive-source} repository on Github as deployment
+key. This way pushes using this key can only go to the
+@code{texlive-source} repository and not anywhere else.
+
+The usage of @code{git-svn} requires a strict discipline to keep a
+linear history in the master branch. Since we are aiming at a pure
+mirror facility, we have decided to further restrict the @code{master}
+branch of the @code{texlive-source} repository on Github to changes by
+@emph{admin}.
+
+This setup allows other developers to branch of @code{master} and
+push their branches to the Github repository, but all updates need to
+from the local @code{master} (not the one on Github) to Subversion and
+back to @code{master} on @code{texlive.info} and from there to Github.
+See below for setup for developers.
+
+@subheading Automatic update of the Git mirror
+
+@emph{admin} has installed a cron job on @code{texlive.info} running
+every 30min which basically runs @code{git svn rebase} and @code{git
+push} in the @code{master} branch of the checkout. The first command
+fetches the changes from the Subversion repository and updates the
+@code{master} branch with them, the second one pushes changes (if
+available) to Github. 
+
+@subheading CI testing on Travis-CI
+
+The @code{source} tree of \TL{} already contains a file
+@code{.travis.yml} which controls the automatic testing on
+Travis-CI. @emph{admin} has registered to Travis-CI and allowed access
+to the Github's @code{TeX-Live} organization's @code{texlive-source}
+repository. The default settings are to build the last commit of each
+push. No further action is necessary on Travis-CI.
+
+In case changes have been pushed during the cron job mentioned above,
+Travis-CI will automatically checkout the last pushed commit and try
+building it.
+
+@subheading Developer setup for Git/Subversion
+
+In case a developer of code in the @TL{} source code wants to use the CI
+testing facility, the following steps are necessary for initialization:
+
+@itemize @bullet
+@item
+Initial @code{git-svn} checkout as laid out above, replacing
+@code{USER} with the Subversion user name. This initial checkout might
+take quite some time as the whole history has to be parsed. In case the
+checkout is interrupted, change into the already created folder and call
+@code{git svn fetch} to continue pulling from the remote until all
+changes have been fetched.
+
+@item
+Adding the Git remote as laid out above. After that it is also necessary
+to set the upstream for the @code{master} branch with
+@code{git branch --set-upstream-to=origin/master master} followed by a
+@code{git pull}. The last command will probably not fetch anything since
+but update the local information about availability.
+
+@end itemize
+
+After this development can be done as follows:
+
+@itemize @bullet
+@item
+Create a new branch based on @code{master}: @code{git checkout -b feature}
+and develop the new features in this branch.
+
+@item
+Pushing the branch to Github will kick of automatic CI testing on this
+branch, too.
+
+@item
+When the feature is ready, first the branch @code{feature} needs to be
+rebased onto current @code{master} with @code{git rebase master}, then
+merged into @code{master}, followed by a submission to the Subversion
+repository via @code{git svn dcommit}. Don't push to master on Github
+(it is anyway protected), your changes will come in in due time via a
+pull on master.
+
+@item
+After the branch is included in master, optionally delete the local and
+rmeote branch @code{feature}.
+
+@end itemize
+
+The above method is the standards and safest method, but there is an
+alternative way by first pulling from Github, and then tricking git-svn
+into believing that everything has been fetched from Subversion
+already. This alternative method is explained XXXXXXXXX (my BLOG?)
+
 @c made from pod doc.
 @include tlbuild-incl/install-tl.texi
 @include tlbuild-incl/tlmgr.texi