From 3021cb3215822aafb4021cf0e44b75b98a76ca86 Mon Sep 17 00:00:00 2001 From: Eric Anholt Date: Tue, 16 Jun 2020 16:42:41 -0700 Subject: [PATCH] docs: Document how to interact with docker containers. There's some text in gitlab-ci.yml, but expand on things a bit here. Reviewed-by: Eric Engestrom Reviewed-by: Erik Faye-Lund Part-of: --- docs/ci/index.rst | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/ci/index.rst b/docs/ci/index.rst index e191d471f0d..3d572c02266 100644 --- a/docs/ci/index.rst +++ b/docs/ci/index.rst @@ -125,3 +125,35 @@ things back up. If this happens, the farm maintainer should provide a report to mesa-dev@lists.freedesktop.org after the fact explaining what happened and what the mitigation plan is for that failure next time. + +Docker caching +-------------- + +The CI system uses docker images extensively to cache +infrequently-updated build content like the CTS. The `freedesktop.org +CI templates +`_ help us +manage the building of the images to reduce how frequently rebuilds +happen, and trim down the images (stripping out manpages, cleaning the +apt cache, and other such common pitfalls of building docker images). + +When running a container job, the templates will look for an existing +build of that image in the container registry under +``FDO_DISTRIBUTION_TAG``. If it's found it will be reused, and if +not, the associated `.gitlab-ci/containers/.sh`` will be run +to build it. So, when developing any change to container build +scripts, you need to update the associated ``FDO_DISTRIBUTION_TAG`` to +a new unique string. We recommend using the current date plus some +string related to your branch (so that if you rebase on someone else's +container update from the same day, you will get a git conflict +instead of silently reusing their container) + +When developing a given change to your docker image, you would have to +bump the tag on each ``git commit --amend`` to your development +branch, which can get tedious. Instad, you can navigate to the +`container registry +`_ for +your repository and delete the tag to force a rebuild. When your code +is eventually merged to master, a full image rebuild will occur again +(forks inherit images from the main repo, but MRs don't propagate +images from the fork into the main repo's registry). -- 2.30.2