How to Report Bugs in apple/container: A Step-by-Step Guide

To report a bug in apple/container, gather your environment details (macOS version, Xcode version, and CLI version), create a new issue using the Bug report template, and fill in the reproduction steps, expected behavior, and actual behavior.

The apple/container repository provides a structured process for filing effective bug reports. According to the source code, the project maintains a dedicated guide at docs/bug-report-how-to.md and a GitHub issue template at .github/ISSUE_TEMPLATE/01-bug.yml to ensure maintainers can reproduce issues quickly.

What Information You Need to Collect

Before opening a new issue, you must gather specific environment data and logs. The bug report guide in docs/bug-report-how-to.md specifies three critical categories of information.

Environment Details

Run the following commands to capture your system configuration:

# Record macOS version

sw_vers

# Record Xcode version

xcodebuild -version

# Record container CLI version

container --version

Reproduction Steps and Logs

Capture verbose output using the debug flag. If the container started but failed later, retrieve its logs:

# Run the failing command with debug output

container --debug create --name test-app ubuntu:latest

# Capture logs if the container exists

container logs test-app > test-app.log

Include the exact commands you executed, all flags and arguments, and any relevant log excerpts or exit codes.

How to Submit a Bug Report

Follow these steps to submit a complete bug report using the official template.

1. Navigate to the Issues tab of the apple/container repository and click New issue.
2. Select the Bug report template (this automatically loads the .github/ISSUE_TEMPLATE/01-bug.yml structure).
3. Fill in the template fields:
   • Paste the reproduction commands inside a fenced code block.
   • Describe the current (buggy) behavior versus the expected behavior.
   • Attach the output from sw_vers, xcodebuild -version, and container --version.
   • Include relevant log sections from your debug output.
4. Review and submit the issue after verifying all required fields are complete.

Example Bug Report Format

When writing your issue description, format the content exactly as shown below to match the template structure:

**Steps to reproduce**
1. `container --debug create --name test-app ubuntu:latest`
2. `container start test-app`

**Actual behavior**

failed to bootstrap container test-app

**Expected behavior**
Container starts and prints its ID.

**Environment**
- macOS: [output of sw_vers]
- Xcode: [output of xcodebuild -version]
- container CLI: [output of container --version]

**Logs**

```bash

# paste relevant portion of test-app.log here

## Key Files and Resources

The following files in the repository provide authoritative guidance on the bug reporting process:

- **[`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md)** – The complete guide covering environment checks, log collection, and report structure.
- **[`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml)** – The GitHub issue template that structures new bug reports with required fields.
- **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)** – Reference documentation for CLI commands including `container --debug` and `container logs`.

## Summary

- **Gather environment data** using `sw_vers`, `xcodebuild -version`, and `container --version` before filing.
- **Capture debug logs** by appending `--debug` to your failing command or using `container logs`.
- **Use the Bug report template** located at [`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml) to ensure consistent formatting.
- **Include exact commands and log output** in fenced code blocks to help maintainers reproduce the issue without clarification.

## Frequently Asked Questions

### Where is the official bug report guide for apple/container?

The official guide is located at [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md) in the repository root. This file contains detailed instructions on preparing environment information, collecting logs, and structuring your report according to the project's standards.

### What commands should I run before submitting a bug report?

You must run `sw_vers` to get macOS details, `xcodebuild -version` for the Xcode version, and `container --version` to record the CLI build. These three outputs provide the baseline environment information required by the issue template in [`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml).

### How do I capture debug logs for a container issue?

Append the `--debug` flag to any `container` command to generate verbose output, such as `container --debug create --name myapp image:tag`. If the container started but exhibits runtime issues, use `container logs <container-id>` to capture the log output for inclusion in your report.

### What is the difference between the bug report guide and the GitHub issue template?

The [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md) file is a comprehensive guide explaining *why* and *how* to collect information, while [`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml) is the structured form that appears when you create a new issue on GitHub. The guide teaches you to prepare the data; the template ensures you enter it in the correct fields.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}