Adding Bug Report Guide (#1292)

## Type of Change - [ ] Bug fix - [ ] New feature - [ ] Breaking change - [x] Documentation update ## Motivation and Context Adding help guide to bug report template to make it easier for users to include relevant information ## Testing - [ ] Tested locally - [ ] Added/updated tests - [x] Added/updated docs
2026-08-24 02:24:19 -05:00 · 2026-04-02 10:48:56 -07:00
parent 745134540e
commit 3eec18214d
2 changed files with 151 additions and 18 deletions
@@ -21,21 +21,20 @@ body:
    id: reproduce
    attributes:
      label: Steps to reproduce
-      description: Explain how to reproduce the incorrect behavior. 
+      description: |
+        Explain how to reproduce the incorrect behavior. 
+        
+        📖 **Need help?** See our guide: [How to write effective reproduction steps](../../docs/bug-report-how-to.md#steps-to-reproduce)
    validations:
      required: true
  - type: textarea
    id: what-happened
    attributes:
-      label: Current behavior
-      description: A concise description of what you're experiencing.
-    validations:
-      required: true
-  - type: textarea
-    id: expected
-    attributes:
-      label: Expected behavior
-      description: A concise description of what you expected to happen.
+      label: Problem description
+      description: |
+        Briefly describe your problem, and what you believe the correct behavior should be.
+        
+        📖 **Need help?** See our guide: [Problem Description](../../docs/bug-report-how-to.md#problem-description)
    validations:
      required: true
  - type: textarea
@@ -46,6 +45,8 @@ body:
          - **OS**: macOS 26.0 (25A354)
          - **Xcode**: Version 26.0 (17A324)
          - **Container**: Container CLI version 0.1.0
+        
+        📖 **Need help gathering this info?** See our guide: [Environment Information](../../docs/bug-report-how-to.md#environment-information)
      value: |
        - OS: 
        - Xcode: 
@@ -53,14 +54,6 @@ body:
      render: markdown
    validations:
      required: true
-  - type: textarea
-    id: logs
-    attributes:
-      label: Relevant log output
-      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
-      value: |
-        N/A
-      render: shell
  - type: checkboxes
    id: terms
    attributes:
@@ -0,0 +1,140 @@
+# How to file effective bug reports
+
+This guide helps you collect the essential information needed to file effective bug reports. Providing complete and accurate information helps maintainers reproduce and fix issues faster.
+
+💡 **Example of a good bug report**: [Issue #1094](https://github.com/apple/container/issues/1094) demonstrates many of the best practices outlined in this guide.
+
+## Steps to reproduce
+
+Clear reproduction steps are essential for maintainers to understand and fix the issue.
+
+### What to include
+1. **Starting state**: What was your setup before the issue?
+   - Fresh installation or existing project?
+   - Any specific configuration files?
+   - Previous commands that led to this state?
+   - Has your machine recently been restarted?
+
+2. **Exact commands**: Copy-paste the exact commands you ran
+   - Include all flags and arguments
+   - Use code blocks for clarity
+
+3. **Reproducibility**: Does it happen every time or intermittently?
+   - Always reproducible
+   - Happens sometimes (describe conditions)
+   - Only happened once
+
+### Example
+```
+1. Create new container: `container create --name test-app ubuntu:latest`
+2. Start the container: `container start test-app`
+3. Container fails during bootstrap with error:
+   "failed to bootstrap container test-app"
+4. Container exits with code 1
+```
+
+## Problem description
+
+Provide a comprehensive description of your problem. Include what currently happens (the bug), what you expect should happen instead, and any relevant log output.
+
+### What to include
+
+#### Current behavior
+- Exact error messages (copy-paste, don't paraphrase)
+- Exit codes or status indicators
+- Performance issues (slowness, hangs, crashes)
+- Unexpected outputs or results
+
+#### Expected behavior
+- The correct output or result you anticipated
+- Reference to documentation if available
+- How it works in previous versions (if applicable)
+- Logical expectations based on the command or action
+
+#### Relevant logs
+Include any log output that helps illustrate the problem:
+- Error messages or stack traces
+- Warning messages related to your issue
+- Output from failed commands
+- Use verbose/debug flags to capture detailed information (see [Log Information](#log-information) section below for how to gather logs)
+
+## Environment information
+
+### Operating system details
+Run this command in Terminal to get your macOS version:
+```bash
+sw_vers
+```
+
+Example output:
+```
+ProductName:		macOS
+ProductVersion:		26.0
+BuildVersion:		12A345
+```
+
+### Xcode version
+Get your Xcode version with:
+```bash
+xcodebuild -version
+```
+
+Example output:
+```
+Xcode 15.0
+Build version 15A240d
+```
+
+### Container CLI version
+Check your Container CLI version:
+```bash
+container --version
+```
+
+Example output:
+```
+container CLI version 0.10.0-27-g9fd15f0 (build: debug, commit: 9fd15f0)
+```
+
+## Log information
+
+### Finding relevant logs
+When reporting issues, include logs that show:
+- Error messages or stack traces
+- Warning messages related to your issue
+- Output from failed commands
+
+### Getting container logs
+For Container CLI issues, run commands with verbose output:
+```bash
+container --debug <command>
+```
+
+You can also use the `container logs` command to get logs from running containers. See the [container logs](command-reference.md#container-logs) documentation for full details.
+```bash
+container logs <container-id>
+```
+
+### System logs
+For system-level container issues, use the built-in system logs command. See the [container system logs](command-reference.md#container-system-logs) documentation for full details.
+```bash
+container system logs
+```
+
+## Common information gaps
+
+### Missing context
+- What were you trying to accomplish?
+- What changed recently in your setup?
+- Does the issue occur in a fresh installation from main?
+
+### Incomplete error information
+- Full error messages (not just the last line)
+- Stack traces where relevant
+- Related warning messages
+
+### Environment variations
+- Does it work with a new instance of the container?
+- Does it work with a fresh install of the Container package?
+- Have your network settings changed?
+- Have your Xcode or macOS versions changed?