OSSForks/ladybird
1
0
Fork 0
mirror of https://github.com/zebrajr/ladybird.git synced 2025-12-06 12:20:00 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Docs: Recommend the standard git workflow

Browse Source 
The standard workflow for working with forks is to clone the fork and
add the main repository as upstream. Also recommend using git switch
instead of checkout.
This commit is contained in:
R-Goc 2025-09-19 19:50:13 +02:00 committed by Jelle Raaijmakers
parent 5b1eba7ac8
commit 71c8ee31fb
1 changed files with 20 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
Documentation/GettingStartedContributing.md
View File

@ -1,9 +1,11 @@
# Getting started contributing to Ladybird # Getting started contributing to Ladybird
Welcome to the Ladybird web browser project! 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. 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 ## Getting familiar with the project
Ladybird is a large project making use of many homegrown and third-party libraries, written primarily in C++. 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: It is recommended you read the README and FAQs in case they already answer any questions you have:
@ -15,14 +17,17 @@ It is recommended you read the README and FAQs in case they already answer any q
The [Discord server](https://discord.gg/nvfjVJ4Svh) is the preferred way to get in contact with the maintainers and community. The [Discord server](https://discord.gg/nvfjVJ4Svh) is the preferred way to get in contact with the maintainers and community.
## Getting familiar with browser engineering in general ## 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](https://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. 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](https://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 ## 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. 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](BuildInstructionsLadybird.md). If you are facing issues, consult the [troubleshooting guide](Troubleshooting.md) and the #build-problems channel on Discord. Carefully follow the steps outlined in the [build instructions](BuildInstructionsLadybird.md). If you are facing issues, consult the [troubleshooting guide](Troubleshooting.md) and the #build-problems channel on Discord.
## Finding bugs and other issues ## Finding bugs and other issues
Here are some of the ways you can find an issue in Ladybird: Here are some of the ways you can find an issue in Ladybird:
* By checking the [issue tracker](https://github.com/LadybirdBrowser/ladybird/issues). * By checking the [issue tracker](https://github.com/LadybirdBrowser/ladybird/issues).
@ -41,15 +46,19 @@ That said, if you _do_ want to start learning some C++ programming yourself, the
The list of [beginner-friendly issues](https://github.com/LadybirdBrowser/ladybird/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) 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. The list of [beginner-friendly issues](https://github.com/LadybirdBrowser/ladybird/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) 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 ## Submitting an issue
If you have found an issue that is not already in the [issue tracker](https://github.com/LadybirdBrowser/ladybird/issues), you may submit it. Do not submit general questions about the project, please use the Discord server instead. If you have found an issue that is not already in the [issue tracker](https://github.com/LadybirdBrowser/ladybird/issues), you may submit it. Do not submit general questions about the project, please use the Discord server instead.
Read the [full contribution guidelines](/CONTRIBUTING.md), 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](/ISSUES.md) for the exact steps to do so. Read the [full contribution guidelines](/CONTRIBUTING.md), 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](/ISSUES.md) for the exact steps to do so.
## Submitting your code ## Submitting your code
### Getting familiar with C++ ### Getting familiar with C++
Ladybird requires at least a basic knowledge of C++, consult a tutorial website like [Learn C++](https://www.learncpp.com/) and online references if you need help. Start small before attempting to make large changes, as they require more in-depth C++ knowledge. Ladybird requires at least a basic knowledge of C++, consult a tutorial website like [Learn C++](https://www.learncpp.com/) 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 ### 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. 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: Developer documentation:
@ -60,34 +69,37 @@ Developer documentation:
* [String formatting](StringFormatting.md) * [String formatting](StringFormatting.md)
### Using `git` ### 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:
The recommended way to work on Ladybird is by forking the main repository on GitHub, then cloning the fork and adding the main repository as a git remote:
```sh ```sh
git remote add myfork git@github.com:MyUsername/ladybird.git git remote add upstream git@github.com:LadybirdBrowser/ladybird.git
``` ```
You can then create a new branch and start making changes to the code: You can then create a new branch and start making changes to the code:
```sh ```sh
git checkout -b mybranch git switch -c mybranch
``` ```
And finally push the commits to your fork: And finally push the commits to your fork:
```sh ```sh
# ONLY run this the first time you push
git push --set-upstream myfork mybranch
# This will work for further pushes
git push git push
``` ```
If you wish to sync your branch with master, or locally resolve merge conflicts, use: If you wish to sync your branch with master, or locally resolve merge conflicts, use:
```sh ```sh
# On mybranch # On mybranch
git fetch origin git fetch upstream
git rebase master git rebase upstream/master
``` ```
You may be asked to perform actions like squashing, rewording, or editing commits. See the [Rewriting history in Git](https://www.youtube.com/watch?v=ElRzTuYln0M) YouTube tutorial for more information. You may be asked to perform actions like squashing, rewording, or editing commits. See the [Rewriting history in Git](https://www.youtube.com/watch?v=ElRzTuYln0M) YouTube tutorial for more information.
### Creating a pull request ### Creating a pull request
Make sure your code meets the requirements in the [full contribution guidelines](/CONTRIBUTING.md) and [coding style](CodingStyle.md). Additionally: Make sure your code meets the requirements in the [full contribution guidelines](/CONTRIBUTING.md) and [coding style](CodingStyle.md). Additionally:
* Make correctly formatted, atomic commits (building the project at every commit should succeed). * Make correctly formatted, atomic commits (building the project at every commit should succeed).