Document lockfile expectations

AGENTS.md

@@ -74,6 +74,8 @@ docs/                     Developer documentation (see below)
 - Labels: always add `tag: ai generated` and at least one `comp:` or `inst:` label + one `type:` label
 - Use `tag: no release notes` for internal/refactoring changes
 - Open as draft first, convert to ready when reviewable
+- Dependency changes: when adding, updating, or removing dependencies, regenerate all affected `gradle.lockfile` files
+  and include them in the same PR. See [lockfile updates](docs/how_to_work_with_gradle.md#updating-lock-files).
 
 ## Review Guidelines
 

CONTRIBUTING.md

@@ -97,6 +97,13 @@ Wildcard imports (`import x.*` or `import static x.*`) are disallowed — see th
 
 When opening a pull request, please open it as a [draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/) to not auto-assign reviewers before the pull request is in a reviewable state.
 
+### Dependency changes
+
+When adding, updating, or removing dependencies, regenerate the `gradle.lockfile` files for all affected modules
+and include them in the same PR.
+This applies to changes in build scripts and `gradle/libs.versions.toml`.
+Follow the [lockfile update workflow](docs/how_to_work_with_gradle.md#updating-lock-files) before requesting review.
+
 ### Title format
 
 Pull request titles should briefly describe the proposed changes in a way that makes sense for the users.

buildSrc/src/test/kotlin/datadog/gradle/plugin/dump/DumpHangedTestIntegrationTest.kt

@@ -74,11 +74,12 @@ class DumpHangedTestIntegrationTest : GradleFixture() {
 
   @Test
   fun `should take dumps`() {
-    val output = runGradleTest(testSleepMillis = 25_0000)
+    // The all-JVM thread sweep can take more than five seconds on busy CI workers.
+    val output = runGradleTest(testSleepMillis = 120_000, timeoutSeconds = 60, dumpOffset = 45)
 
     // Assert Gradle output has evidence of taking dumps.
     assertTrue(output.contains("Taking dumps after 15 seconds delay for :test"))
-    assertTrue(output.contains("Requesting stop of task ':test' as it has exceeded its configured timeout of 20s."))
+    assertTrue(output.contains("Requesting stop of task ':test' as it has exceeded its configured timeout of 1m."))
     assertTrue(buildDir.exists()) // Assert build happened.
 
     val dumps = buildFile("dumps")
@@ -279,6 +280,7 @@ class DumpHangedTestIntegrationTest : GradleFixture() {
   private fun File.toIbmJdk(): IbmJdk? {
     val release = File(this, "release").takeIf { it.isFile } ?: return null
     val properties = Properties().apply { release.inputStream().use { load(it) } }
+
     // Values in `release` are quoted, e.g. IMPLEMENTOR="IBM Corporation".
     fun property(name: String) = properties.getProperty(name).orEmpty().trim('"')
 

docs/how_to_work_with_gradle.md

@@ -895,20 +895,25 @@ All projects have dependency locking enabled via the `dd-trace-java.dependency-l
 
 #### Updating Lock Files
 
-Lock files are automatically updated weekly by CI. To update them manually:
+When adding, updating, or removing a dependency in a build script or `gradle/libs.versions.toml`,
+regenerate the lockfiles for all affected modules and include them in the same PR.
+Shared dependencies can affect multiple modules.
 
 ```bash
-# Update all lock files in the repository
+# Regenerate lockfiles for all projects
 ./gradlew resolveAndLockAll --write-locks
 
-# Update lock files for a specific project
-./gradlew :dd-trace-api:dependencies --write-locks
+# Regenerate lockfiles for a specific project, e.g. dd-trace-api
+./gradlew :dd-trace-api:resolveAndLockAll --write-locks
 ```
 
+> [!NOTE]
+> Lock files are also automatically updated weekly by CI.
+
 > [!IMPORTANT]
-> This project uses **lenient lock mode** (`LockMode.LENIENT`), which allows the build to succeed 
-> even if locked dependencies can't be resolved. This prevents build failures when dependencies 
-> are temporarily unavailable or when resolution conflicts occur.
+> This project uses **lenient lock mode** (`LockMode.LENIENT`), which permits dependency changes without failing
+> lock validation.
+> This prevents build failures when dependencies are temporarily unavailable or when resolution conflicts occur.
 
 #### When Lock Files Are Used
 
@@ -933,14 +938,15 @@ cat dd-trace-api/gradle.lockfile
 
 #### Lock File Workflow
 
-1. **Developer adds a dependency**: The dependency is resolved using the current version rules
-2. **Run with `--write-locks`**: Gradle resolves all configurations and writes exact versions to lock files
-3. **Commit lock files**: Include `gradle.lockfile` changes in your commit
-4. **CI validates**: Builds use locked versions for reproducibility
-5. **Weekly CI job**: Automatically updates all lock files to pick up new versions
+1. **Change dependencies**: Add, update, or remove dependencies in build scripts or the version catalog
+2. **Regenerate lockfiles**: Run `resolveAndLockAll --write-locks` for all affected projects
+3. **Include lockfiles**: Review the generated changes and include affected `gradle.lockfile` files in the same PR
+4. **CI builds**: Builds read the updated lockfiles; lenient mode does not enforce lockfile consistency
+5. **Weekly CI job**: Refreshes floating versions independently of dependency PRs
 
-> [!NOTE]> **Instrumentation modules often use version ranges** (e.g., `[3.0,3.12.12]`) to test 
-> against multiple library versions. Dependency locking pins these ranges to specific versions in 
+> [!NOTE]
+> **Instrumentation modules often use version ranges** (e.g., `[3.0,3.12.12]`) to test
+> against multiple library versions. Dependency locking pins these ranges to specific versions in
 > lock files, ensuring consistent test behavior.
 
 ## Useful dd-trace-java Extensions