Improve messages around dependency spec management (#17969)

* Improve messages around dependency spec management

1. Validation says which commands can fix the failure.
2. Freeze/sync have docs that make it clear what they do and how they differ.
3. Freeze says what it's doing to the "static file"

* add changelog

* adjust test

Author: iliakur

datadog_checks_dev/changelog.d/17969.fixed

@@ -0,0 +1 @@
+Improve messages around dependency spec management

datadog_checks_dev/datadog_checks/dev/tooling/commands/validate/dep.py

@@ -241,7 +241,11 @@ def dep(check, require_base_check_version, min_base_check_version):
             message = (
                 f'Mismatch for dependency `{name}`:\n'
                 f'    Agent: {" | ".join(sorted(agent_dependency_definitions))}\n'
-                f'    Checks: {" | ".join(sorted(check_dependency_definitions))}'
+                f'    Checks: {" | ".join(sorted(check_dependency_definitions))}\n'
+                'If you think the Agent requirements are correct, run:\n'
+                'ddev dep sync\n'
+                'If you think the Checks requirements are correct, run:\n'
+                'ddev dep freeze'
             )
             echo_failure(message)
             annotate_error(agent_dependencies_file, message)

ddev/changelog.d/17969.fixed

@@ -0,0 +1 @@
+Improve messages around dependency spec management

ddev/src/ddev/cli/dep/freeze.py

@@ -10,10 +10,14 @@
 )
 
 
-@click.command(short_help="Combine all dependencies for the Agent's static environment")
+@click.command()
 @click.pass_obj
 def freeze(app):
-    """Combine all dependencies for the Agent's static environment."""
+    """
+    Combine all dependencies for the Agent's static environment.
+
+    This reads and merges the dependency specs from individual integrations and writes them to agent_requirements.in
+    """
     dependencies, errors = read_check_dependencies(app.repo)
 
     if errors:
@@ -22,5 +26,5 @@ def freeze(app):
 
         app.abort()
 
-    app.display_info(f'Static file: {app.repo.agent_requirements}')
+    app.display_info(f'Writing combined requirements to: {app.repo.agent_requirements}')
     update_agent_dependencies(app.repo, dependencies)

ddev/src/ddev/cli/dep/sync.py

@@ -19,11 +19,15 @@ def get_dependency_set(python_versions):
     }
 
 
-@click.command(
-    short_help="Update integrations' dependencies so that they match the Agent's static environment",
-)
+@click.command()
 @click.pass_obj
 def sync(app):
+    """
+    Synchronize integration dependency spec with that of the agent as a whole.
+
+    Reads dependency spec from agent_requirements.in and propagates it to all integrations.
+    For each integration we propagate only the relevant parts (i.e. its direct dependencies).
+    """
     agent_dependencies, errors = read_agent_dependencies(app.repo)
 
     if errors:

ddev/tests/cli/test_dep.py

@@ -46,7 +46,7 @@ def test_freeze(ddev, fake_repo):
     agent_requirements_path = fake_repo / 'agent_requirements.in'
 
     assert result.exit_code == 0
-    assert result.output == f'Static file: {agent_requirements_path}\n'
+    assert result.output == f'Writing combined requirements to: {agent_requirements_path}\n'
 
     requirements = agent_requirements_path.read_text()