Ladybird is an ambitious, from-scratch web browser built primarily in C++. Because the project is still in a pre-alpha stage of development, there are many high-value ways to help out that do not require writing or modifying C++ code at all — including systematic testing, standards discussion, and precise bug reports. This guide covers everything you need to know to become a productive contributor from day one.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ladybirdBrowser/ladybird/llms.txt
Use this file to discover all available pages before exploring further.
Ladybird is developed exclusively by a group of project maintainers. Pull requests from non-maintainers are not
accepted, and code-change proposals through other routes are not supported. Your involvement still matters
enormously: clear bug reports, reproducible test-case reductions, website testing, standards discussion, design
feedback, and security reports all move the project forward.
Getting Familiar with the Project
Start by reading the project README and FAQ — they answer many common questions about the project’s goals, scope, and current state. Once you have a feel for the big picture, join the community on Discord.Discord Server
The preferred way to reach maintainers and the broader community. Use the
#build-problems channel for build issues.Web Browser Engineering
A free online book that walks through building a complete browser engine in Python — a great primer before reading Ladybird’s C++ code.
Project Governance
Ladybird is driven by the Ladybird Browser Initiative, a 501(c)(3) non-profit organization. The project maintains a strict neutrality policy: all discussion and work is kept strictly related to browser development and web standards. Societal or political topics are discouraged in project spaces so the community can remain focused on its shared goal.Getting Involved
Learn the basics of C++
Ladybird requires at least a foundational knowledge of C++. If you need a refresher, Learn C++ is a well-regarded free resource. You do not need to be an expert before starting — many early contributions involve JavaScript-only WPT test reductions.
Build the browser
Ladybird must be built from source. The project natively supports Linux and macOS; Windows users require WSL. Follow the build instructions carefully, and consult the troubleshooting guide or the
#build-problems Discord channel if you run into problems.Find something to work on
There are several good entry points for finding issues (see below). If you are new to browser internals, starting with WPT test failures is strongly recommended.
Report the issue
Before filing, search the issue tracker to confirm the bug is not already known. Then follow the issue policy and the detailed issue-reporting guidelines to write a high-quality report.
Finding Bugs and Other Issues
There are many concrete ways to surface actionable problems in Ladybird:- Issue tracker — Browse open issues for something that interests you or that you can help reduce.
- Manual browsing — Use the browser as you normally would and note anything that behaves differently from other browsers.
- WPT.fyi — Visit WPT.fyi results for Ladybird to find failing or timing-out tests. You do not need to submit individual test failures as issues.
- Timing-out WPT tests — The Ladybird WPT timeout filter is a good focused list; for a real-world walk-through, see the “Fixing a WPT timeout in Window.postMessage()” video.
- Callgrind profiling — Use Callgrind to identify hot code paths or inefficiencies.
- TODO/FIXME comments — Search the codebase for
TODOandFIXMEannotations.
Submitting a Good Issue
Follow these guidelines when filing a bug:- One bug per issue. Combining multiple problems makes discussion and resolution unnecessarily complicated.
- Follow the detailed issue-reporting guidelines. The guidelines explain exactly how to reduce a reproduction case and how to describe expected versus actual behavior.
- No build issues or support requests. If the GitHub Actions CI build passes, the problem is almost certainly on your local machine. Debug it locally or ask in
#build-problemson Discord. - No off-topic commentary. Hundreds of people receive issue notifications — keep comments relevant and technical.
- General questions belong on Discord, not in the issue tracker.
Learning the Codebase
The AK Library
Ladybird uses its own AK library in place of the C++ STL. AK provides containers (Vector, HashMap,
FixedArray), string types (ByteString, String, StringView), smart pointers (OwnPtr, RefPtr, WeakPtr),
and error-handling utilities (ErrorOr, the TRY and MUST macros). Most AK facilities are not separately
documented; the best way to learn them is to read the header files and find existing usage examples in the codebase.
Developer Documentation
Coding Style
Naming conventions, clang-format requirements, member prefixes, and punctuation rules for all Ladybird C++ code.
Patterns
TRY/MUST error propagation macros, fallible constructors, and the smart pointer hierarchy.
Testing
How to run, write, and rebaseline Text, Layout, Ref, Screenshot, and Web Platform Tests.
Human Language Policy
Ladybird treats human language with the same care as programming language. The following rules apply to all user-facing strings, code comments, commit messages, and issue reports:- The official project language is American English with ISO 8601 dates and metric units.
- Use proper spelling, grammar, and punctuation.
- Write in an authoritative and technical tone.
- Avoid contractions, slang, and idioms.
- Avoid humor, sarcasm, and other forms of non-literal language.
- Use gender-neutral pronouns, except when referring to a specific person.
This policy applies even to debug logging and other internal strings, because they may be exposed to end users in the
future.