[workspace] Withdraw stable API support for several externals (#17324)

* [workspace] Withdraw stable API support for several externals

These are the python- and models-only repositories that should not be public.

The models already have Drake-public filegroup wrappers where appropriate.
The python libraries are either maintainer-only code (github3, template),
or else brittle interior dependencies (clang) of private tools (mkdoc).

examples/hydroelastic/spatula_slip_control/BUILD.bazel

@@ -6,15 +6,15 @@ load("@drake//tools/lint:lint.bzl", "add_lint_tests")
 load("//tools/install:install_data.bzl", "install_data")
 load("@drake//tools/workspace:forward_files.bzl", "forward_files")
 load(
-    "//tools/workspace/models:files.bzl",
+    "//tools/workspace/models_internal:files.bzl",
     "wsg_50_hydro_bubble_mesh_files",
 )
 
 _WSG_50_HYDRO_BUBBLE_MESHES = forward_files(
-    srcs = ["@models//:" +
+    srcs = ["@models_internal//:" +
             x for x in wsg_50_hydro_bubble_mesh_files()],
     dest_prefix = "",
-    strip_prefix = "@models//:wsg_50_hydro_bubble/",
+    strip_prefix = "@models_internal//:wsg_50_hydro_bubble/",
     visibility = ["//visibility:private"],
 )
 

examples/multibody/strandbeest/BUILD.bazel

@@ -3,7 +3,7 @@
 
 load("@drake//tools/skylark:drake_cc.bzl", "drake_cc_binary")
 load("@drake//tools/skylark:drake_py.bzl", "drake_py_unittest")
-load("@drake//tools/workspace/ros_xacro:defs.bzl", "xacro_file")
+load("@drake//tools/workspace/ros_xacro_internal:defs.bzl", "xacro_file")
 load("@drake//tools/lint:lint.bzl", "add_lint_tests")
 
 xacro_file(

examples/quadrotor/BUILD.bazel

@@ -9,7 +9,7 @@ load(
 load("//tools/install:install_data.bzl", "install_data")
 load("//tools/lint:lint.bzl", "add_lint_tests")
 load("//tools/workspace:forward_files.bzl", "forward_files")
-load("//tools/workspace/models:files.bzl", "skydio_2_mesh_files")
+load("//tools/workspace/models_internal:files.bzl", "skydio_2_mesh_files")
 
 package(
     default_visibility = [
@@ -18,9 +18,9 @@ package(
 )
 
 _SKYDIO_2_MESHES = forward_files(
-    srcs = ["@models//:" + x for x in skydio_2_mesh_files()],
+    srcs = ["@models_internal//:" + x for x in skydio_2_mesh_files()],
     dest_prefix = "",
-    strip_prefix = "@models//:skydio_2/",
+    strip_prefix = "@models_internal//:skydio_2/",
     visibility = ["//visibility:private"],
 )
 

geometry/profiling/BUILD.bazel

@@ -8,9 +8,9 @@ load("//tools/lint:lint.bzl", "add_lint_tests")
 load("@drake//tools/workspace:forward_files.bzl", "forward_files")
 
 _EVO_MESH = forward_files(
-    srcs = ["@models//:dishes/bowls/evo_bowl_no_mtl.obj"],
+    srcs = ["@models_internal//:dishes/bowls/evo_bowl_no_mtl.obj"],
     dest_prefix = "",
-    strip_prefix = "@models//:dishes/bowls/",
+    strip_prefix = "@models_internal//:dishes/bowls/",
     visibility = ["//visibility:private"],
 )
 

manipulation/models/franka_description/BUILD.bazel

@@ -7,7 +7,10 @@ load(
 load("//tools/install:install_data.bzl", "install_data")
 load("//tools/lint:lint.bzl", "add_lint_tests")
 load("@drake//tools/workspace:forward_files.bzl", "forward_files")
-load("//tools/workspace/models:files.bzl", "franka_description_mesh_files")
+load(
+    "//tools/workspace/models_internal:files.bzl",
+    "franka_description_mesh_files",
+)
 
 # This package is public so that other packages can refer to
 # individual files in model from their bazel rules.
@@ -16,9 +19,12 @@ package(
 )
 
 _FRANKA_DESCRIPTION_MESHES = forward_files(
-    srcs = ["@models//:" + x for x in franka_description_mesh_files()],
+    srcs = [
+        "@models_internal//:" + x
+        for x in franka_description_mesh_files()
+    ],
     dest_prefix = "",
-    strip_prefix = "@models//:franka_description/",
+    strip_prefix = "@models_internal//:franka_description/",
     visibility = ["//visibility:private"],
 )
 

manipulation/models/jaco_description/BUILD.bazel

@@ -7,16 +7,19 @@ load(
 load("//tools/install:install_data.bzl", "install_data")
 load("//tools/lint:lint.bzl", "add_lint_tests")
 load("@drake//tools/workspace:forward_files.bzl", "forward_files")
-load("//tools/workspace/models:files.bzl", "jaco_description_mesh_files")
+load(
+    "//tools/workspace/models_internal:files.bzl",
+    "jaco_description_mesh_files",
+)
 
 package(
     default_visibility = [":__subpackages__"],
 )
 
 _JACO_DESCRIPTION_MESHES = forward_files(
-    srcs = ["@models//:" + x for x in jaco_description_mesh_files()],
+    srcs = ["@models_internal//:" + x for x in jaco_description_mesh_files()],
     dest_prefix = "",
-    strip_prefix = "@models//:jaco_description/",
+    strip_prefix = "@models_internal//:jaco_description/",
     visibility = ["//visibility:private"],
 )
 

manipulation/models/realsense2_description/BUILD.bazel

@@ -8,7 +8,7 @@ load(
 )
 load("@drake//tools/workspace:forward_files.bzl", "forward_files")
 load(
-    "@drake//tools/workspace/intel_realsense_ros:files.bzl",
+    "@drake//tools/workspace/intel_realsense_ros_internal:files.bzl",
     "realsense2_description_files",
 )
 
@@ -19,10 +19,10 @@ package(
 )
 
 _REALSENSE2_DESCRIPTION_FILES = forward_files(
-    srcs = ["@intel_realsense_ros//:" +
+    srcs = ["@intel_realsense_ros_internal//:" +
             x for x in realsense2_description_files()],
     dest_prefix = "",
-    strip_prefix = "@intel_realsense_ros//:realsense2_description/",
+    strip_prefix = "@intel_realsense_ros_internal//:realsense2_description/",
     visibility = ["//visibility:private"],
 )
 

manipulation/models/wsg_50_description/BUILD.bazel

@@ -6,16 +6,22 @@ load(
 load("//tools/install:install_data.bzl", "install_data")
 load("//tools/lint:lint.bzl", "add_lint_tests")
 load("@drake//tools/workspace:forward_files.bzl", "forward_files")
-load("//tools/workspace/models:files.bzl", "wsg_50_description_mesh_files")
+load(
+    "//tools/workspace/models_internal:files.bzl",
+    "wsg_50_description_mesh_files",
+)
 
 package(
     default_visibility = [":__subpackages__"],
 )
 
 _WSG_50_DESCRIPTION_MESHES = forward_files(
-    srcs = ["@models//:" + x for x in wsg_50_description_mesh_files()],
+    srcs = [
+        "@models_internal//:" + x
+        for x in wsg_50_description_mesh_files()
+    ],
     dest_prefix = "",
-    strip_prefix = "@models//:wsg_50_description/",
+    strip_prefix = "@models_internal//:wsg_50_description/",
     visibility = ["//visibility:private"],
 )
 

manipulation/models/ycb/BUILD.bazel

@@ -7,7 +7,7 @@ load(
 load("@drake//tools/install:install_data.bzl", "install_data")
 load("//tools/lint:lint.bzl", "add_lint_tests")
 load("@drake//tools/workspace:forward_files.bzl", "forward_files")
-load("//tools/workspace/models:files.bzl", "ycb_mesh_files")
+load("//tools/workspace/models_internal:files.bzl", "ycb_mesh_files")
 
 # This package is public so that other packages can refer to
 # individual files in model from their bazel rules.
@@ -16,9 +16,9 @@ package(
 )
 
 _YCB_MESHES = forward_files(
-    srcs = ["@models//:" + x for x in ycb_mesh_files()],
+    srcs = ["@models_internal//:" + x for x in ycb_mesh_files()],
     dest_prefix = "",
-    strip_prefix = "@models//:ycb/",
+    strip_prefix = "@models_internal//:ycb/",
     visibility = ["//visibility:private"],
 )
 

manipulation/util/show_model.py

@@ -88,7 +88,7 @@ def add_filename_and_parser_argparse_arguments(args_parser):
         "--find_resource", action="store_true",
         help="Use FindResourceOrThrow to resolve the filename to a Drake "
              "resource. Use this if the supporting data files are a generated "
-             "by Bazel (e.g. the OBJs or PNGs are in @models).")
+             "by Bazel (e.g. the OBJs or PNGs are in @models_internal).")
     args_parser.add_argument(
         "--package_path", type=str, default=None,
         help="Full path to the root package for reading in SDF resources.")

multibody/parsing/BUILD.bazel

@@ -9,7 +9,10 @@ load(
 )
 load("//tools/lint:lint.bzl", "add_lint_tests")
 load("@drake//tools/workspace:forward_files.bzl", "forward_files")
-load("//tools/workspace/dm_control:files.bzl", "dm_control_mujoco_files")
+load(
+    "//tools/workspace/dm_control_internal:files.bzl",
+    "dm_control_mujoco_files",
+)
 
 filegroup(
     name = "test_models",
@@ -422,9 +425,9 @@ drake_cc_googletest(
 )
 
 _DM_CONTROL_MUJOCO_FILES = forward_files(
-    srcs = ["@dm_control//:" + x for x in dm_control_mujoco_files()],
+    srcs = ["@dm_control_internal//:" + x for x in dm_control_mujoco_files()],
     dest_prefix = "",
-    strip_prefix = "@dm_control//:",
+    strip_prefix = "@dm_control_internal//:",
     visibility = ["//visibility:private"],
 )
 

tools/release_engineering/BUILD.bazel

@@ -17,7 +17,7 @@ drake_py_binary_ubuntu_only(
     name = "relnotes",
     srcs = ["relnotes.py"],
     deps = [
-        "@github3_py",
+        "@github3_py_internal//:github3_py",
     ],
 )
 

tools/workspace/BUILD.bazel

@@ -40,7 +40,7 @@ drake_py_binary(
     visibility = ["//visibility:private"],
     deps = [
         ":module_py",
-        "@github3_py",
+        "@github3_py_internal//:github3_py",
     ],
 )
 

tools/workspace/README.md

@@ -26,6 +26,10 @@ Drake is using:
   https://docs.bazel.build/versions/master/be/workspace.html
   https://docs.bazel.build/versions/master/skylark/repository_rules.html
 
+Per the [Stability Guidelines](https://drake.mit.edu/stable.html), externals
+named as "internal" or otherwise documented to be "internal use only" are
+not subject to any deprecation guarantees.
+
 # Semi-automated monthly upgrades
 
 Drake maintainers will use the ``bazel-bin/tools/workspace/new_release`` tool
@@ -222,6 +226,13 @@ difficult to support on multiple platforms.
 TODO(jwnimmer-tri) Add documentation here about how to validate that the new
 software's license is acceptable to use within Drake.
 
+When adding a new external, decide whether it will be covered by our
+[Stability Guidelines](https://drake.mit.edu/stable.html). Broadly speaking,
+dependencies that come from the host operating system can be covered as
+stable, but dependencies that we compile from source code should be internal.
+If the new dependency should be in internal, name it like "foo_internal" (not
+just "foo") throughout all of the below.
+
 Referring to some new third-party software as "foo", the steps to incorporate
 it into Drake are roughly:
 

tools/workspace/clang_cindex_python3/repository.bzl → tools/workspace/clang_cindex_python3_internal/repository.bzl

@@ -2,15 +2,15 @@
 
 load("@drake//tools/workspace:github.bzl", "github_archive")
 
-def clang_cindex_python3_repository(
+def clang_cindex_python3_internal_repository(
         name,
         mirrors = None):
     github_archive(
         name = name,
         repository = "wjakob/clang-cindex-python3",
         commit = "9dcf4f16757c9b6446910e4de51ed27ee962b81b",
         sha256 = "65c26ec7fe09c54479ce5f375ccd5dd11e4e8bb11e47681c254be0d9bcd79164",  # noqa
-        build_file = "@drake//tools/workspace/clang_cindex_python3:package.BUILD.bazel",  # noqa
+        build_file = "@drake//tools/workspace/clang_cindex_python3_internal:package.BUILD.bazel",  # noqa
         mirrors = mirrors,
         patch_cmds = ["mkdir clang && mv *.py clang"],
     )