This page documents the process for reporting issues and submitting pull requests to the Dear ImGui repository. It covers the templates, requirements, and best practices for contributing to the project through GitHub's issue tracker and pull request system. For general contribution guidelines including coding standards, see Contribution Guidelines.
The Dear ImGui project uses two primary channels for community interaction:
The project provides structured templates to ensure contributors provide necessary information efficiently, respecting maintainer time and attention.
Decision Logic: Issues are for users who have successfully integrated Dear ImGui and are experiencing bugs, requesting features, or discussing usage patterns. Discussions are specifically for first-time integration problems.
Sources: docs/CONTRIBUTING.md26-37
The issue template is defined as a YAML form in .github/ISSUE_TEMPLATE/issue_template.yml using GitHub's issue form schema. The template enforces structured information gathering through typed input fields with validation.
GitHub Issue Form Field Types:
| Field ID | Type | Required | YAML Path | Purpose |
|---|---|---|---|---|
specs_version | input | Yes | body[2] | Dear ImGui version and branch (e.g., "Version 1.92, Branch: master") |
specs_backend | input | Yes | body[3] | Backend files used (e.g., "imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp") |
specs_compiler_os | input | Yes | body[4] | Compiler and OS (e.g., "Windows 11 + MSVC 2022") |
specs_full | textarea | No | body[5] | Full config from Demo->Tools->About Dear ImGui->Config/Build Info |
issue_description | textarea | Yes | body[6] | Detailed problem description, goals, expectations |
screenshots | textarea | No | body[7] | Visual context via images/GIF/video (drag files to upload) |
repro_code | textarea | No | body[8] | Minimal, Complete, Verifiable Example (MCVE) |
The form includes two markdown type fields at the beginning for warnings and prerequisite checklists. The validations.required field at .github/ISSUE_TEMPLATE/issue_template.yml30-47 enforces that critical fields must be filled before issue submission.
Sources: .github/ISSUE_TEMPLATE/issue_template.yml1-93
The issue template enforces several critical pieces of information at .github/ISSUE_TEMPLATE/issue_template.yml23-67:
Version Information: Always specify the exact Dear ImGui version and branch. This is critical because the codebase evolves rapidly and behavior differs between branches (master, docking, etc.).
Backend Specification: Platform and renderer backends must be specified. The combination matters because issues often arise from backend-specific code in files like imgui_impl_glfw.cpp, imgui_impl_vulkan.cpp, etc.
Compiler and OS: Compilation and platform-specific issues are common. The maintainer needs to know the exact toolchain.
The Minimal, Complete, and Verifiable Example is strongly encouraged at docs/CONTRIBUTING.md52 The repro_code textarea field at .github/ISSUE_TEMPLATE/issue_template.yml76-87 provides a pre-formatted C++ code block:
MCVE Requirements:
| Requirement | Details |
|---|---|
| Pasteable | Code must work in examples/*/main.cpp or imgui_demo.cpp without modification |
| Minimal | Remove all extraneous code unrelated to the issue |
| Complete | Include all necessary context (no missing variables or functions) |
| Verifiable | Must reliably reproduce the issue when run |
The contribution guidelines note that "Often while creating the MCVE you will solve the problem!" because the process of isolating code forces understanding of the root cause.
Sources: docs/CONTRIBUTING.md52 .github/ISSUE_TEMPLATE/issue_template.yml76-87
Screenshots, GIFs, and videos are strongly encouraged at docs/CONTRIBUTING.md53 The template's screenshots field at .github/ISSUE_TEMPLATE/issue_template.yml68-74 includes the note "You can drag files here" to facilitate attachment.
Visual Asset Guidelines:
Issues involving crashes must include debugger callstacks at docs/CONTRIBUTING.md54-55 The guidelines require:
IM_ASSERT(false); in main() function to verify asserts are activeIM_ASSERT() calls are scattered throughout the codebase with explanatory commentsIM_ASSERT() calls the standard assert() function (can be redefined in imconfig.h)Sources: docs/CONTRIBUTING.md39-59 .github/ISSUE_TEMPLATE/issue_template.yml48-88
The pull request template is minimal at .github/pull_request_template.md1-11 but references comprehensive guidelines:
Sources: .github/pull_request_template.md1-11
A critical requirement stated at .github/pull_request_template.md5 and docs/CONTRIBUTING.md74:
One PR = One Branch: Each pull request must use a dedicated branch separate from master or main. The template explicitly states: "Make sure you're using a special branch just for this pull request."
Git Workflow:
This branch-per-PR model enables:
Pull requests must follow existing code style at docs/CONTRIBUTING.md73:
| Standard | Requirement |
|---|---|
| Indentation | 4 spaces (no tabs) |
| Variable naming | local_variable |
| Function naming | FunctionName() |
| Member naming | MemberName |
| Comments | // Text Comment for documentation, //CodeComment(); for code |
| Casts | C-style casts |
| C++ features | Minimal C++11 usage, avoid modern C++ idioms |
Examples under examples/ may deviate to match ecosystem conventions (e.g., DirectX samples match Microsoft style).
When submitting a PR at docs/CONTRIBUTING.md68-72:
For Features:
For Bug Fixes:
For All PRs:
Sources: docs/CONTRIBUTING.md66-74
Key Lifecycle Stages:
| Stage | Actor | Requirements |
|---|---|---|
| Fork/Branch | Contributor | Create dedicated branch per .github/pull_request_template.md5 |
| Implementation | Contributor | Follow style guide: 4 spaces, FunctionName(), MemberName, C-style casts |
| Testing | Contributor | Run imgui_test_suite from imgui_test_engine |
| Template Clearing | Contributor | Delete template content at .github/pull_request_template.md9 before submission |
| Review | Maintainer | Evaluates code quality and long-term maintenance burden |
| Revision | Contributor | Push to same branch; PR updates automatically |
Sources: docs/CONTRIBUTING.md66-74 .github/pull_request_template.md1-11
All contributions are subject to specific copyright terms at docs/CONTRIBUTING.md76-81:
When submitting code, contributors agree that:
This ensures the maintainer has full control over the project's future direction and licensing decisions.
Sources: docs/CONTRIBUTING.md76-81
The contribution guidelines include strict moderation policies at docs/CONTRIBUTING.md41-63:
Issues may be closed prematurely if:
Users may be blocked for:
The guidelines explicitly state at docs/CONTRIBUTING.md45:
"OPEN-SOURCE SOFTWARE LIVES OR DIES BY THE AMOUNT OF ENERGY MAINTAINERS CAN SPARE. WE HAVE LOTS OF STUFF TO DO. THIS IS AN ATTENTION ECONOMY AND MANY LAZY OR MINOR ISSUES ARE HOGGING OUR ATTENTION AND DRAINING ENERGY."
This philosophy emphasizes that maintainer time is the project's most valuable resource.
Sources: docs/CONTRIBUTING.md39-63
The issue template system is configured at .github/ISSUE_TEMPLATE/config.yml1:
Configuration Effect: This setting enforces that all issues must use the structured YAML form template. Users cannot create blank issues without filling the required fields.
The template header at .github/ISSUE_TEMPLATE/issue_template.yml7 redirects first-time users with build/link/run issues to GitHub Discussions instead:
This two-tier system ensures:
Sources: .github/ISSUE_TEMPLATE/config.yml1 .github/ISSUE_TEMPLATE/issue_template.yml1-12
Sources: docs/CONTRIBUTING.md1-82 .github/pull_request_template.md1-11 .github/ISSUE_TEMPLATE/issue_template.yml1-93
Refresh this wiki