From 50963e4c38921b2bfc1f81adf4a72c6984824b71 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Thu, 7 Jun 2018 09:12:25 +0900 Subject: start work on CI documentation --- Build/source/doc/tlbuild.texi | 134 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) 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 -- cgit v1.2.3