Welcome to the first lesson of our "Contribution Workflow and Bug Triage" module. In the previous module, we moved from the theory of LLVM IR to the practical skill of generating it from C++ code. You are now equipped to take a piece of source code and see how the compiler represents it internally, a critical first step in debugging.
Today, we take the next logical step on your path to becoming an LLVM contributor. We will focus on where to find the work that needs to be done: the LLVM issue tracker. This lesson directly addresses the learning outcome: Search and filter the LLVM GitHub issues for subprojects like Clang, LLDB, and MLIR. Mastering this skill is your gateway to the LLVM community. It's how you will find your first bug to fix, engage with experienced developers, and ultimately build the portfolio needed for your GSoC application.
The Central Hub: The LLVM-Project Issue Tracker
The entire LLVM ecosystem, from Clang and MLIR to LLDB and the core optimizer, centralizes its bug tracking in one place: the llvm/llvm-project repository on GitHub. This is where bugs are reported, feature requests are made, and technical problems are discussed.
As of today, this tracker contains tens of thousands of open issues. Navigating this vast sea of information without a strategy is impossible. Your most powerful tool for this task is the filtering mechanism, particularly the use of labels.
Anatomy of an LLVM Issue
Before we dive into filtering, let's look at what a typical issue looks like. Every issue has a title, a description, an issue number, and, most importantly for our purposes, a set of labels.
The title gives you a quick summary, but the labels are what allow for systematic searching and categorization.
Filtering by Sub-project with Labels
The LLVM community uses a structured labeling system to organize issues by the component they relate to. Most component labels are prefixed with the name of the sub-project or area. This convention is the key to narrowing your search.
Common prefixes you will encounter include:
clang:for the Clang C/C++/Objective-C frontend.mlir:for the Multi-Level Intermediate Representation framework.lldb:for the LLDB debugger.backend:for specific code generation targets (e.g.,backend:x86).opt:for specific optimization passes.
To find issues for a specific sub-project, you use the label: filter in the GitHub search bar. For example, to find all open issues related to MLIR, you would search for:is:issue is:open label:mlir
Let's explore the issue tracker to see this in practice.
This is the main issues page for the LLVM project. We'll use it to understand the layout and the label system.
First, look at the main search bar. This is where you will construct your queries. Notice the default query is is:issue is:open. Next, examine the list of issues on the page. Pay close attention to the colored labels attached to each one, such as clang:frontend, libc, and HLSL. This demonstrates the component-based labeling system in action.
The Nuances of a Living Label System
As with any large, long-running software project, the labeling system has evolved and has its own quirks. Understanding these nuances can make your searches more effective. A key point of discussion within the community has been the use of project-specific labels (e.g., llvm:crash) versus combining a generic label (crash) with a project "umbrella" label (llvm).
This is not just a trivial administrative detail; it reflects the challenges of organizing information in a way that is compatible with the available tooling (i.e., GitHub's search capabilities).
Llvm:crash vs crash label - GitHub - LLVM Discussion Forums
This discussion from the LLVM Discourse forums provides a fascinating look into the rationale behind the label system's design. It's a great example of the meta-level thinking required to manage a project of this scale.
Read through the thread, focusing on these key points: The initial post outlines the problem: redundant labels like llvm:crash and crash. A core suggestion emerges: use orthogonal labels, such as label:llvm label:crash. This is a powerful search strategy. Finally, note the practical reason for this structure: GitHub's search limitations prevent wildcard searches like label:'llvm:*', making explicit umbrella labels necessary.
The key takeaway from this discussion is that your searches may need to combine labels. To find all crashes in the core LLVM libraries, a more robust query might be: is:issue is:open label:llvm label:crash.
Finding Your First Bug: "Good First Issues"
Your primary goal is to start contributing. The LLVM community actively helps new contributors by curating a list of bugs that are considered suitable for someone new to the project. These are marked with the good first issue label.
This is the single most important label for you right now. You can find all such issues with this query:is:issue is:open label:"good first issue"
To make this more targeted, you can combine it with the component labels you're interested in. Given your interest in GSoC projects, you might focus on Clang, MLIR, or LLDB.
Here are some powerful, targeted queries to get you started:
- Good first issues in Clang:
is:issue is:open label:"good first issue" label:clang - Good first issues in MLIR:
is:issue is:open label:"good first issue" label:mlir - Good first issues in the Clang static analyzer:
is:issue is:open label:"good first issue" label:clang-static-analyzer - Good first issues that are documentation-related (often a great starting point):
is:issue is:open label:"good first issue" label:documentation
Go to the LLVM GitHub issues page now and try running these queries yourself. Read through a few of the results to get a feel for the kinds of problems they describe. This is no longer an academic exercise; you are now looking at real bugs that you could potentially fix.
Conclusion
In this lesson, you've learned the essential skill of navigating the LLVM project's issue tracker. This is the starting point for all contributions. You now know how to find the pulse of the project and, more importantly, how to find your place within it.
Key Takeaways:
- The LLVM issue tracker on GitHub is the central repository for all bugs and feature requests.
- The primary method for navigating issues is by filtering with labels.
- Sub-project issues are typically categorized with prefixed labels like
clang:,mlir:, andlldb:. - Complex searches can be constructed by combining multiple labels, such as
label:mlir label:bug. - The
good first issuelabel is your most valuable tool for finding beginner-friendly tasks that will help you get started as a contributor.
You've learned how to find an issue. The next logical question is, "Where is the code that's causing this issue?" In our next lesson, we will address that by learning how to navigate the LLVM source tree directory structure to locate core components. This will connect the bug report to the actual code you'll need to understand and modify.