[doc] Fix model_version_control instructions

[jwnimmer-tri]

Closes #19822.

+@rpoyner-tri for feature review, please.
+@RussTedrake for platform review, please.

---

This change is 

[RussTedrake]

thanks.

Reviewed 5 of 5 files at r1, all commit messages.
Reviewable status: 2 unresolved discussions, LGTM missing from assignee rpoyner-tri(platform)

---

doc/_pages/model_version_control.md line 17 at r1 (raw file):

[RobotLocomotion/models](https://github.com/RobotLocomotion/models). Please do
not commit files that are generally small, like ``*.sdf`` or ``*.urdf`` files,
in ``RobotLocomotion/models``; instead, please commit those directly.

are we officially changing our stance on this? I like the idea of having the model repo assets be standalone. But I also see the benefit of having small changes not require the two-repo-two-step.

---

doc/_pages/model_version_control.md line 34 at r1 (raw file):

   they are needed, typically via ``filegroup(name = "models", ...)``. You can
   grep for ``@drake_models`` to find examples of using existing model files. Do
   not add an ``install()`` rule for files from ``drake_models``.

btw - the mistake I made was to add the remote assets to an existing filegroup that was being installed lower in the bazel file.

Suggestion. replace the last sentence with: "Make sure that the filegroup containing files from drake_models is not installed via an install() rule."

(possible install_data(), too?)

[jwnimmer-tri]

Reviewable status: 1 unresolved discussion, LGTM missing from assignee rpoyner-tri(platform)

---

doc/_pages/model_version_control.md line 17 at r1 (raw file):

Previously, RussTedrake (Russ Tedrake) wrote…

are we officially changing our stance on this? I like the idea of having the model repo assets be standalone. But I also see the benefit of having small changes not require the two-repo-two-step.

Per #13942, I thought our consensus is that model files should live all in one place. (For small models, the whole thing can live in package://drake/. For models with large files, all inter-related files should live in package://drake_models/. to remain cohesive.)

If this is too much change for this PR, I can back out this edit for now and work on it in 13942. My hope was that removing the advice that's opposite to our goal would be a small mitigation for now.

---

doc/_pages/model_version_control.md line 34 at r1 (raw file):

Previously, RussTedrake (Russ Tedrake) wrote…

btw - the mistake I made was to add the remote assets to an existing filegroup that was being installed lower in the bazel file.

Suggestion. replace the last sentence with: "Make sure that the filegroup containing files from drake_models is not installed via an install() rule."

(possible install_data(), too?)

I updated the text a bit. I don't think it's too much of a hazard any more, for two reasons:

(1) As of the pending #19861, any installed @drake_models files should be a bazel hard error, not a warning.

(2) Grepping for @drake_models, as suggested by the text here, will only find correct examples to imitate.

[RussTedrake]

Reviewed 1 of 1 files at r2, all commit messages.
Reviewable status: LGTM missing from assignee rpoyner-tri(platform)

---

doc/_pages/model_version_control.md line 17 at r1 (raw file):

Previously, jwnimmer-tri (Jeremy Nimmer) wrote…

Per #13942, I thought our consensus is that model files should live all in one place. (For small models, the whole thing can live in package://drake/. For models with large files, all inter-related files should live in package://drake_models/. to remain cohesive.)

If this is too much change for this PR, I can back out this edit for now and work on it in 13942. My hope was that removing the advice that's opposite to our goal would be a small mitigation for now.

I agree that it's fine to go ahead with the change for this PR. I didn't know about (or had forgotten about) #13942.

[rpoyner-tri]

Reviewed 4 of 5 files at r1, 1 of 1 files at r2, all commit messages.
Reviewable status: complete! all discussions resolved, LGTM from assignees rpoyner-tri(platform),RussTedrake(platform)