From 3eec18214d8ab5401dac55ac7547468fc472a3dc Mon Sep 17 00:00:00 2001 From: AJ Emory <239216119+ajemory@users.noreply.github.com> Date: Thu, 2 Apr 2026 10:48:56 -0700 Subject: [PATCH] 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 --- .github/ISSUE_TEMPLATE/01-bug.yml | 29 +++---- docs/bug-report-how-to.md | 140 ++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+), 18 deletions(-) create mode 100644 docs/bug-report-how-to.md diff --git a/.github/ISSUE_TEMPLATE/01-bug.yml b/.github/ISSUE_TEMPLATE/01-bug.yml index 6b99d30e..1a89d48d 100644 --- a/.github/ISSUE_TEMPLATE/01-bug.yml +++ b/.github/ISSUE_TEMPLATE/01-bug.yml @@ -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: diff --git a/docs/bug-report-how-to.md b/docs/bug-report-how-to.md new file mode 100644 index 00000000..8b699458 --- /dev/null +++ b/docs/bug-report-how-to.md @@ -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 +``` + +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 +``` + +### 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?