Merge pull request #23877 from docker/agent/issue-23194

docs: address issue #23194

Author: dvdksn

.github/workflows/agent.yml

@@ -26,12 +26,16 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
+      - name: Install dependencies
+        run: npm ci
+
       - name: Create branch
         run: |
           git checkout -b agent/issue-${{ github.event.issue.number }}
 
       - name: Run agent
         uses: docker/[email protected]
+        timeout-minutes: 15
         with:
           cagent-version: v1.15.5
           agent: ./agent.yml

.gitignore

@@ -15,4 +15,4 @@ cagent
 # cagent tmp files
 .cagent
 .upstream-issues.md
-.validation-log.md
+.validation.log

content/manuals/build/building/best-practices.md

@@ -77,30 +77,51 @@ dependencies can considerably lower the attack surface.
 
 ## Rebuild your images often
 
-Docker images are immutable. Building an image is taking a snapshot of that
-image at that moment. That includes any base images, libraries, or other
-software you use in your build. To keep your images up-to-date and secure, make
-sure to rebuild your image often, with updated dependencies.
+Docker images are immutable. Building an image is taking a snapshot of
+that image at that moment. That includes any base images, libraries, or
+other software you use in your build. To keep your images up-to-date and
+secure, rebuild your images regularly with updated dependencies.
 
-To ensure that you're getting the latest versions of dependencies in your build,
-you can use the `--no-cache` option to avoid cache hits.
+### Use --pull to get fresh base images
 
-```console
-$ docker build --no-cache -t my-image:my-tag .
-```
-
-The following Dockerfile uses the `24.04` tag of the `ubuntu` image. Over time,
-that tag may resolve to a different underlying version of the `ubuntu` image,
-as the publisher rebuilds the image with new security patches and updated
-libraries. Using the `--no-cache`, you can avoid cache hits and ensure a fresh
-download of base images and dependencies.
+The following Dockerfile uses the `24.04` tag of the `ubuntu` image.
+Over time, that tag may resolve to a different underlying version of the
+`ubuntu` image, as the publisher rebuilds the image with new security
+patches and updated libraries.
 
 ```dockerfile
 # syntax=docker/dockerfile:1
 FROM ubuntu:24.04
 RUN apt-get -y update && apt-get install -y --no-install-recommends python3
 ```
 
+To get the latest version of the base image, use the `--pull` flag:
+
+```console
+$ docker build --pull -t my-image:my-tag .
+```
+
+The `--pull` flag forces Docker to check for and download a newer
+version of the base image, even if you have a version cached locally.
+
+### Use --no-cache for clean builds
+
+The `--no-cache` flag disables the build cache, forcing Docker to
+rebuild all layers from scratch:
+
+```console
+$ docker build --no-cache -t my-image:my-tag .
+```
+
+This gets the latest available versions of dependencies from package
+managers like `apt-get` or `npm`. However, `--no-cache` doesn't pull a
+fresh base image - it only prevents reusing cached layers. For a
+completely fresh build with the latest base image, combine both flags:
+
+```console
+$ docker build --pull --no-cache -t my-image:my-tag .
+```
+
 Also consider [pinning base image versions](#pin-base-image-versions).
 
 ## Exclude with .dockerignore
@@ -639,10 +660,10 @@ RUN ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet
 ```
 
 For more information about `ADD` or `COPY`, see the following:
+
 - [Dockerfile reference for the ADD instruction](/reference/dockerfile.md#add)
 - [Dockerfile reference for the COPY instruction](/reference/dockerfile.md#copy)
 
-
 ### ENTRYPOINT
 
 The best use for `ENTRYPOINT` is to set the image's main command, allowing that
@@ -695,7 +716,6 @@ fi
 exec "$@"
 ```
 
-
 This script uses [the `exec` Bash command](https://wiki.bash-hackers.org/commands/builtin/exec) so that the final running application becomes the container's PID 1. This allows the application to receive any Unix signals sent to the container. For more information, see the [`ENTRYPOINT` reference](/reference/dockerfile.md#entrypoint).
 
 In the following example, a helper script is copied into the container and run via `ENTRYPOINT` on