docs(docker): add image tag naming convention and version pinning gui…

sources/platform/actors/development/actor_definition/docker.md

@@ -49,6 +49,101 @@ These images come with Python (version `3.9`, `3.10`, `3.11`, `3.12`, or `3.13`)
 | [`actor-python-playwright`](https://hub.docker.com/r/apify/actor-python-playwright) | Debian image with [`playwright`](https://github.com/microsoft/playwright) and all its browsers. |
 | [`actor-python-selenium`](https://hub.docker.com/r/apify/actor-python-selenium) | Debian image with [`selenium`](https://github.com/seleniumhq/selenium), Google Chrome, and [ChromeDriver](https://developer.chrome.com/docs/chromedriver/). |
 
+## Image tag naming convention
+
+Docker image tags follow a consistent naming pattern that allows you to pin specific versions:
+
+### Node.js images
+
+For Node.js images, the tag format is:
+
+- `{node-version}` - A Node.js version only (e.g., `20`, `22`, `24`)
+- `{node-version}-{library-version}` - A Node.js version with pinned Playwright/Puppeteer version (e.g., `22-1.52.0`)
+
+Examples:
+
+| Tag | Description |
+| --- | ----------- |
+| `20` | Node.js 20 with the Playwright/Puppeteer version that was latest when the image was built |
+| `22` | Node.js 22 with the Playwright/Puppeteer version that was latest when the image was built |
+| `22-1.52.0` | Node.js 22 with Playwright/Puppeteer version 1.52.0 pinned |
+| `latest` | Latest LTS Node.js version |
+
+### Python images
+
+For Python images, the tag format is:
+
+- `{python-version}` - A Python version only (e.g., `3.11`, `3.12`, `3.13`)
+- `{python-version}-{library-version}` - A Python version with pinned Playwright/Selenium version
+
+### Available tags
+
+To see all available tags for an image, visit Docker Hub:
+
+- [View actor-node-playwright-chrome tags](https://hub.docker.com/r/apify/actor-node-playwright-chrome/tags)
+- [View actor-node-playwright tags](https://hub.docker.com/r/apify/actor-node-playwright/tags)
+- [View actor-node-puppeteer-chrome tags](https://hub.docker.com/r/apify/actor-node-puppeteer-chrome/tags)
+- [View actor-python-playwright tags](https://hub.docker.com/r/apify/actor-python-playwright/tags)
+
+You can also query available tags programmatically:
+
+```bash
+curl -s "https://registry.hub.docker.com/v2/repositories/apify/actor-node-playwright-chrome/tags?page_size=50" | jq '.results[].name'
+```
+
+## Version pinning for reproducible builds
+
+For production Actors, pin both the Node.js/Python version and the browser automation library version in your Dockerfile. This ensures reproducible builds and prevents unexpected behavior when new versions are released.
+
+### Recommended approach
+
+In your `Dockerfile`, use a fully pinned tag:
+
+```dockerfile
+# Pin both Node.js 22 and Playwright 1.52.0
+FROM apify/actor-node-playwright-chrome:22-1.52.0
+```
+
+In your `package.json`, match the Playwright/Puppeteer version to your Docker image tag:
+
+```json
+{
+    "dependencies": {
+        "apify": "^3.5.0",
+        "@crawlee/playwright": "^3.15.0",
+        "playwright": "1.52.0"
+    }
+}
+```
+
+:::warning Why version matching matters
+
+When the Playwright/Puppeteer version in your `package.json` differs from what's pre-installed in the Docker image, npm will download and install the version specified in `package.json`. This can lead to:
+
+- Slower builds due to downloading browser binaries
+- Potential version incompatibilities
+- Inconsistent behavior between local development and production
+
+:::
+
+### Using `*` as version (alternative approach)
+
+You may encounter older documentation or templates using `*` as the Playwright/Puppeteer version:
+
+```json
+{
+    "dependencies": {
+        "playwright": "*"
+    }
+}
+```
+
+The asterisk (`*`) tells npm to use whatever version is already installed, which prevents re-downloading the library. While this approach still works, **pinning specific versions is now preferred** because:
+
+1. Reproducibility - Your builds will behave the same way regardless of when you build them
+1. Predictability - You know exactly which version you're running
+1. Debugging - Version-specific issues are easier to track down
+
 ## Custom Dockerfile
 
 Apify uses Docker to build and run Actors. If you create an Actor from a template, it already contains an optimized `Dockerfile` for the given use case.