docs: Add timeout-inside-lock example

Explain how to place timeout() inside lock() so that queue wait time
does not count against the timeout deadline.

Fixes #740

Author: mPokornyETM

src/doc/examples/readme.md

@@ -10,4 +10,5 @@ If you have a question, please open a [GitHub issue](https://github.com/jenkinsc
 - [Locking multiple stages in declarative pipeline](locking-multiple-stages-in-declarative-pipeline.md)
 - [Locking a random free resource](locking-random-free-resource.md)
 - [Scripted vs declarative pipeline](scripted-vs-declarative-pipeline.md)
+- [Timeout inside lock](timeout-inside-lock.md)
 - [Dynamic resource pool expansion](dynamic-resource-pool-expansion.md)

src/doc/examples/timeout-inside-lock.md

@@ -0,0 +1,76 @@
+# Timeout Inside Lock
+
+When a pipeline uses both `timeout` and `lock`, the placement of `timeout`
+determines whether queue wait time counts against the deadline.
+
+## Problem
+
+If `timeout` wraps the entire pipeline or stage, the clock starts before the
+lock is acquired. A job that waits a long time in the queue may time out
+before it gets a chance to run:
+
+```groovy
+pipeline {
+  agent any
+  options {
+    // Clock starts immediately — includes queue wait time!
+    timeout(time: 5, unit: 'HOURS')
+  }
+  stages {
+    stage('Deploy') {
+      steps {
+        lock('my-resource') {
+          echo 'Deploying...'
+        }
+      }
+    }
+  }
+}
+```
+
+## Solution
+
+Place `timeout` **inside** `lock` so the countdown begins only after the
+resource has been acquired:
+
+```groovy
+pipeline {
+  agent any
+  stages {
+    stage('Deploy') {
+      steps {
+        lock('my-resource') {
+          timeout(time: 5, unit: 'HOURS') {
+            echo 'Deploying...'
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+This way a job can wait in the queue as long as necessary without the
+timeout expiring prematurely.
+
+## Stage-level variant
+
+The same pattern works with `options` at the stage level:
+
+```groovy
+pipeline {
+  agent any
+  stages {
+    stage('Deploy') {
+      options {
+        lock('my-resource')
+      }
+      steps {
+        timeout(time: 5, unit: 'HOURS') {
+          echo 'Deploying...'
+        }
+      }
+    }
+  }
+}
+```