From 8958e13878514bbd232f10c2c3bddb1dc962f2ef Mon Sep 17 00:00:00 2001 From: Yuval Tassa Date: Wed, 15 Jun 2022 01:05:38 -0700 Subject: [PATCH] Improve best-practice description of included models in GitHub issues. PiperOrigin-RevId: 455060429 Change-Id: I6a4544e99436749590a8d46ada09777ce2e90330 --- .github/ISSUE_TEMPLATE/ask_for_help.md | 48 ++++++++++++++++++++++++++ .github/ISSUE_TEMPLATE/help.md | 16 --------- README.md | 23 +++++++----- 3 files changed, 62 insertions(+), 25 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/ask_for_help.md delete mode 100644 .github/ISSUE_TEMPLATE/help.md diff --git a/.github/ISSUE_TEMPLATE/ask_for_help.md b/.github/ISSUE_TEMPLATE/ask_for_help.md new file mode 100644 index 00000000..19106a7d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/ask_for_help.md @@ -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: + +
+ minimal XML + +```XML + + + + + + + + + + + + + + + + +``` + +
+ +Here is a screenshot / video, illustrating my question: diff --git a/.github/ISSUE_TEMPLATE/help.md b/.github/ISSUE_TEMPLATE/help.md deleted file mode 100644 index 8b34900a..00000000 --- a/.github/ISSUE_TEMPLATE/help.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/README.md b/README.md index e9894eb0..bf5b94aa 100644 --- a/README.md +++ b/README.md @@ -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