diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 58 |
1 files changed, 48 insertions, 10 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index be13b6de3..7e94957eb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -261,24 +261,62 @@ commit automatically with `git commit -s`. All code changes must pass ``make validate`` and ``make lint``, as executed in a standard container. The container image for this -purpose is provided at: ``quay.io/libpod/gate:latest``. However, -for changes to the image itself, it may also be built locally -from the repository root, with the command: +purpose is provided at: ``quay.io/libpod/gate:master``. With +other tags available for different branches as needed. These +images are built automatically after merges to the branch. + +#### Building the gate container locally + +For local use, debugging, or experimentation, the gate image may +be built locally from the repository root, with the command: ``` -sudo podman build -t quay.io/libpod/gate:latest -f contrib/gate/Dockerfile . +podman build -t gate -f contrib/gate/Dockerfile . ``` ***N/B:*** **don't miss the dot (.) at the end, it's really important** -The container executes 'make' by default, on a copy of the repository. -This avoids changing or leaving build artifacts in your working directory. +#### Local use of gate container + +The gate container's entry-point executes 'make' by default, on a copy of +the repository made at runtime. This avoids the container changing or +leaving build artifacts in your hosts working directory. It also guarantees +every execution is based upon pristine code provided from the host. + Execution does not require any special permissions from the host. However, -the repository root must be bind-mounted into the container at -'/usr/src/libpod'. For example, running `make lint` is done (from -the repository root) with the command: +your libpod repository clone's root must be bind-mounted to the container at +'/usr/src/libpod'. The copy will be made into /var/tmp/go (`$GOSRC` in container) +before running your make target. For example, running `make lint` from a +repository clone at $HOME/devel/libpod could be done with the commands: + +```bash +$ cd $HOME/devel/libpod +$ podman run -it --rm -v $PWD:/usr/src/libpod:ro \ + --security-opt label=disable quay.io/libpod/gate:master \ + lint +``` + +***N/B:*** Depending on your clone's git remotes-configuration, +(esp. for `validate` and `lint` targets), you may also need to reference the +commit which was your upstream fork-point. Otherwise you may receive an error +similar to: -``sudo podman run -it --rm -v $PWD:/usr/src/libpod:ro --security-opt label=disable quay.io/libpod/gate:latest lint`` +``` +fatal: Not a valid object name master +Makefile:152: *** Required variable EPOCH_TEST_COMMIT value is undefined, whitespace, or empty. Stop. +``` + +For example, assuming your have a remote called `upstream` running the +validate target should be done like this: + +```bash +$ cd $HOME/devel/libpod +$ git remote update upstream +$ export EPOCH_TEST_COMMIT=$(git merge-base upstream/master HEAD) +$ podman run -it --rm -e EPOCH_TEST_COMMIT -v $PWD:/usr/src/libpod:ro \ + --security-opt label=disable quay.io/libpod/gate:master \ + validate +``` ### Integration Tests |