Skip to content

Latest commit

 

History

History
95 lines (68 loc) · 6.72 KB

GettingStartedContributing.md

File metadata and controls

95 lines (68 loc) · 6.72 KB
Raw

Getting started contributing to Ladybird

Welcome to the Ladybird web browser project!

This document aims to be a beginner-friendly guide to your first Ladybird contribution; remember to read the linked documentation for more information.

Getting familiar with the project

Ladybird is a large project making use of many homegrown and third-party libraries, written primarily in C++.

It is recommended you read the README and FAQs in case they already answer any questions you have:

The Discord server is the preferred way to get in contact with the maintainers and community.

Getting familiar with browser engineering in general

If you’ve never worked on browser-engine code before, and you’re not sure where to begin — one great place to get started is by reading the book Web Browser Engineering. It explains how browser engines in general work, and how they’re built — by walking you through real code for actually building all the parts of a basic but complete browser engine (networking code, HTML parsing, layout engine, JavaScript handling, and more), in a couple thousand lines of Python.

Building the code

Ladybird must be built from source during this pre-alpha stage of development, and currently natively supports Linux and macOS; running it on Windows requires WSL.

Carefully follow the steps outlined in the build instructions. If you are facing issues, consult the troubleshooting guide and the #build-problems channel on Discord.

Finding bugs and other issues

Here are some of the ways you can find an issue in Ladybird:

  • By checking the issue tracker.
  • Manually, by using the browser as you normally would.
  • By finding failing WPT tests on WPT.fyi. Note that while fixes are welcome, you don't need to submit issue reports for individual tests.
  • By finding WPT tests on WPT.fyi that are timing out in Ladybird. For a real-world walk-through of doing that from start to finish with an actual timing-out-in-Ladybird test case, see the “Fixing a WPT timeout in Window.postMessage()” “browser hacking” video.
  • By using a profiling tool such as Callgrind to find code that can be improved.

If you’re not necessarily already a proficient C++ programmer, beginning by troubleshooting WPT tests may be the very best way to get started contributing to the project — especially if you do already have some proficiency with frontend JavaScript code.

That’s because without even knowing any C++ at all, you can still — by working just with the JavaScript code in the WPT test source — get a long way toward isolating the cause of a particular WPT test failure or timeout. And that alone can be a very big help to other contributors who can then follow up on your work by digging further into the related C++ code.

That said, if you do want to start learning some C++ programming yourself, then working from a WPT test case may be the very best way for you on your own to start — by getting an understanding of how and where the JavaScript code in the WPT test ends up calling into the related C++ code in the Ladybird sources — and then start fixing the underlying problem in the C++ code on your own.

The list of beginner-friendly issues is usually very short, and there currently isn't a strict roadmap of issues to address first. It is ultimately up to you to choose a task that you feel comfortable working on.

Submitting an issue

If you have found an issue that is not already in the issue tracker, you may submit it. Do not submit general questions about the project, please use the Discord server instead.

Read the full contribution guidelines, in particular the Issue policy and Human language policy. It is recommended you reduce the website to the most minimal amount of HTML/CSS/JS which still results in the error (if applicable), and provide the result expected from other browsers vs Ladybird. Read the detailed issue-reporting guidelines for the exact steps to do so.

Submitting your code

Getting familiar with C++

Ladybird requires at least a basic knowledge of C++, consult a tutorial website like Learn C++ and online references if you need help. Start small before attempting to make large changes, as they require more in-depth C++ knowledge.

Getting familiar with the codebase

Ladybird makes use of the included AK library instead of the C++ STL, and employs a specific coding style based around it. Unfortunately most AK and internal library facilities are not documented; you may need to look for the header files, and examples of usage in existing code.

Developer documentation:

Using git

The recommended way to work on Ladybird is by cloning the main repository locally, then forking it on GitHub and adding your repository as a Git remote:

git remote add myfork git@github.com:MyUsername/ladybird.git

You can then create a new branch and start making changes to the code:

git checkout -b mybranch

And finally push the commits to your fork:

# ONLY run this the first time you push
git push --set-upstream myfork mybranch
# This will work for further pushes
git push

If you wish to sync your branch with master, or locally resolve merge conflicts, use:

# On mybranch
git fetch origin
git rebase master

You may be asked to perform actions like squashing, rewording, or editing commits. See the Rewriting history in Git YouTube tutorial for more information.

Creating a pull request

Make sure your code meets the requirements in the full contribution guidelines and coding style. Additionally:

  • Make correctly formatted, atomic commits (building the project at every commit should succeed).
  • Discuss and resolve any reviews you receive.
  • Fix CI failures by editing your commits.
  • Include tests (use Meta/import-wpt-test.py to import WPT tests)