Expand the bug issue template & add a template for questions (#873)

mhucka · web-flow · commit e2473d497aa7 · 2025-08-27T14:55:25.000-07:00
diff --git a/.github/ISSUE_TEMPLATE/1-bug-report.yml b/.github/ISSUE_TEMPLATE/1-bug-report.yml
@@ -1,37 +1,66 @@
 name: Bug report
 description: Report a problem with qsim or this project
-type: Bug
 body:
   - type: markdown
     attributes:
       value: |
-        Thank you for taking the time to fill out this bug report!
+        Thank you for taking the time to open an issue report. Before
+        continuing, it's worth [searching through the existing issues in this
+        repository](https://github.com/quantumlib/qsim/issues?q=is%3Aissue) in
+        case the same topic has already been reported.
 
   - type: textarea
     attributes:
       label: Describe the issue
       description: >-
-        Please explain clearly and in detail what the issue is. What led up
-        to it, or how did you encounter it?
+        Please explain clearly and in detail what the issue is. What were you
+        trying to do? What happened? What was unexpected about what happened?
+      placeholder: >-
+        Describe the issue here
     validations:
       required: true
 
-  - type: input
-    attributes:
-      label: What version of qsim are you using?
-    validations:
-      required: false
-
   - type: textarea
     attributes:
-      label: How can the issue be reproduced?
+      label: Tell us how to reproduce the issue
       description: >-
-        Explain in a step-by-step fashion what someone else would need to
+        Explain in a step-by-step fashion what someone else will need to
         do in order to reproduce the issue. If possible, include literal
         examples of commands or code using [Markdown fenced code
         blocks](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks).
         For long output, paste the text into [collapsed
         sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
         or attach text files.
+      placeholder: >-
+        Write a step-by-step explanation of how to reproduce the issue here
+    validations:
+      required: false
+
+  - type: input
+    attributes:
+      label: Tell us the version of qsim or qsimcirq (if relevant)
+      description: |-
+        For qsim software problems, we need to know the exact version you are
+        using. If you are using the Python package and are running within a
+        terminal emulator, then typing the following command in the shell will
+        print the version number:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+        ```python3 -c 'import qsimcirq; print(qsimcirq.__version__)'```<br>
+        If you are using a Google Colab or Jupyter notebook environment,
+        then running the following command in a notebook cell will print
+        the version number:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+        `import qsimcirq; print(qsimcirq.__version__)`
+      placeholder: >-
+        Write the qsim version number here
+    validations:
+      required: false
+
+  - type: input
+    attributes:
+      label: Tell us the computing environment (if relevant)
+      description: >-
+        Please tell us if you are using Linux, macOS, Windows, Google Colab, or
+        something else, and its version.
+      placeholder: >-
+        Describe the computing environment and its version here
     validations:
       required: false
diff --git a/.github/ISSUE_TEMPLATE/2-feature-request.yml b/.github/ISSUE_TEMPLATE/2-feature-request.yml
@@ -1,19 +1,25 @@
 name: Feature request
-description: Request a new feature or change in qsim
+description: Request a feature or suggest an enhancement
 type: Enhancement
 body:
   - type: markdown
     attributes:
-      value: |
-        Thank you for taking the time to fill out this feature request form!
+      value: >-
+        Thank you for your interest in qsim! Before continuing, it's worth
+        [searching through the existing issues in this
+        repository](https://github.com/quantumlib/qsim/issues?q=is%3Aissue) in
+        case the same feature has already been requested.
 
   - type: textarea
     attributes:
-      label: Is your feature request related to a use case or problem?
+      label: What is your request or suggestion?
       description: >-
-        Please tell us the context of your request. Is it to help you do
-        something that you currently cannot due to limitations in qsim, or is it
-        an idea for an enhancement or new functionality, or something else?
+        Please describe the request and its context in detail. Is the feature
+        something that would help you do something that you currently cannot due
+        to limitations in qsim, or is it an idea for an enhancement or new
+        functionality, or something else?
+      placeholder: >-
+        Describe the feature request here
     validations:
       required: true
 
@@ -24,6 +30,8 @@ body:
         If you have ideas or preferences for the solution, you can let us know
         here. If you are aware of other similar or related work, please let us
         know about it here.
+      placeholder: >-
+        Describe your proposed solution here
     validations:
       required: false
 
@@ -34,7 +42,7 @@ body:
         Please choose from among the following options. If the lack of this
         feature is blocking important work, please choose from among P0–P2.
       options:
-        - P0 – needed no later than a week
+        - P0 – needed within two weeks
         - P1 – needed by the next release
         - P2 – needed within two quarters
         - P3 – not blocked; it's an idea
diff --git a/.github/ISSUE_TEMPLATE/3-question.yml b/.github/ISSUE_TEMPLATE/3-question.yml
@@ -0,0 +1,43 @@
+name: Question
+description: As a question
+type: Question
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Thank you for your interest in qsim! Before continuing, it's worth
+        [searching through the existing issues in this
+        repository](https://github.com/quantumlib/qsim/issues?q=is%3Aissue) in
+        case the same question has already been asked and possibly answered.
+
+  - type: textarea
+    attributes:
+      label: What is the question?
+      description: >-
+        Please provide enough details and contextual information so that the
+        question is answerable.
+      placeholder: >-
+        Write your question here
+    validations:
+      required: true
+
+  - type: input
+    attributes:
+      label: Does this concern a specific version of qsim? If so, what version?
+      placeholder: >-
+        Write the qsim version number here
+    validations:
+      required: false
+
+  - type: input
+    attributes:
+      label: Is it specific to a computing environment? If so, which one?
+      description: >-
+        If the platform and operating system version may be relevant, please
+        tell us those details as well. It may matter, for example, whether you
+        are using Linux, macOS, Windows, or Google Colab, as well as whether
+        you are trying to use CUDA (and what version), and other details.
+      placeholder: >-
+        Describe the computing environment here
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/4-task.yml b/.github/ISSUE_TEMPLATE/4-task.yml
@@ -4,18 +4,25 @@ type: Task
 body:
   - type: markdown
     attributes:
-      value: |
-        Thank you for taking the time to fill out this feature request form!
+      value: >-
+        Thank you for your interest in qsim! Before continuing, it's worth
+        [searching through the existing issues in this
+        repository](https://github.com/quantumlib/qsim/issues?q=is%3Aissue) in
+        case the same or similar task already exists.
 
   - type: textarea
     attributes:
       label: What is the task?
+      placeholder: >-
+        Describe the task here
     validations:
       required: true
 
   - type: textarea
     attributes:
       label: (Optional) Do you have ideas or preferences for the approach?
+      placeholder: >-
+        Describe a suggested or preferred approach here
     validations:
       required: false
 
@@ -26,7 +33,7 @@ body:
         Please choose from among the following options. If the lack of this
         feature is blocking important work, please choose from among P0–P2.
       options:
-        - P0 – needed no later than a week
+        - P0 – needed within two weeks
         - P1 – needed by the next release
         - P2 – needed within two quarters
         - P3 – not blocked; it's an idea
