Improve best-practice description of included models in GitHub issues.

PiperOrigin-RevId: 455060429 Change-Id: I6a4544e99436749590a8d46ada09777ce2e90330
2022-06-15 01:05:38 -07:00
parent 2de8aa9e92
commit 8958e13878
3 changed files with 62 additions and 25 deletions
@@ -0,0 +1,48 @@
+---
+name: Asking for help
+about: Request help from the developers and the community
+title: ''
+labels: question
+assignees: ''
+
+---
+
+**How to ask for help**
+
+First, read our quick guide to
+[asking good questions](https://github.com/deepmind/mujoco#asking-questions).
+Below is a template for you to use:
+
+Hi,
+
+I'm a (student / professor / engineer) and I'm trying to use MuJoCo for _____.
+
+I'm looking for some help with ____.
+
+Here is a model which explains my question:
+
+<details>
+  <summary>minimal XML</summary>
+
+```XML
+<mujoco>
+  <worldbody>
+    <light pos=".4 -.4 .3" dir="-2 2 -1.5" diffuse=".6 .6 .6"/>
+    <light pos="-.2 -.4 .3" dir="1 2 -1.5" diffuse=".6 .6 .6"/>
+    <geom type="plane" size=".5 .5 .01"/>
+    <body name="ball" pos="0 0 0.05">
+      <freejoint/>
+      <geom size=".03"/>
+    </body>
+    <body name="hammer" pos="-.05 0 0.18">
+      <joint axis="0 1 0"/>
+      <geom type="capsule" size=".01" fromto="0 0 0 -.15 0 0"/>
+      <geom type="box" size=".02 .02 .03" pos="-.15 0 0"/>
+    </body>
+  </worldbody>
+</mujoco>
+```
+
+</details>
+
+Here is a screenshot / video, illustrating my question:
@@ -1,16 +0,0 @@
---
-name: Help
-about: Ask for help with MuJoCo
-title: ''
-labels: question
-assignees: ''
-
---
-
-**How to ask for help**
-
- Take a step back and tell us what you're trying to accomplish, and in what context. The more information you give, the better the answers you will get.
-
- If relevant, include a ***minimal*** model that demonstrates the problem. If the model is small, include it as inline XML. If it requires binary assets, attach it as a zip file.
-
- Include a screenshot or video, if relevant.
@@ -75,25 +75,30 @@ Here are some guidelines for asking good questions:
   You can add comments to existing threads or start new ones. If you start a
   new thread and there are existing relevant threads, please link to them.

-2. Use a clear and descriptive title.
+2. Use a clear and specific title. Try to include keywords that will make your
+   question easy for other to find in the future.

 3. Introduce yourself and your project more generally.

   If your level of expertise is exceptional (either high or low), and it might
   be relevant to what we can assume you know, please state that as well.

-4. Make it easy for others to reproduce the problem or understand your question.
+4. Take a step back and tell us what you're trying to accomplish, if we
+   understand you goal we might suggest a different type of solution than the
+   one you are having problems with

-   If this requires a model, please include it. Short, minimal, pure XML models
-   (the preferred format) should be pasted inline. Longer XML models should be
-   attached as a `.txt` file (GitHub does not accept `.xml`) or in a `.zip`.
-   Models requiring binary assets (meshes, textures), should be attached as
-   `.zip` files. Please remember to make sure the included model is loadable
+5. Make it easy for others to reproduce the problem or understand your question.
+
+   If this requires a model, please include it. Try to make the model minimal:
+   remove elements that are unrelated to your question. Pure XML models should
+   be inlined. Models requiring binary assets (meshes, textures), should be
+   attached as a `.zip` file. Please make sure the included model is loadable
   before you attach it.

-5. Include an illustrative screenshot or video, if relevant.
+6. Include an illustrative screenshot or video, if relevant.

-6. Tell us which MuJoCo version and operating system you are using.
+7. Tell us how you are accessing MuJoCo (C API, Python bindings, etc.) and which
+   MuJoCo version and operating system you are using.

 ## Citation