Skip to content

Commit 71c8ee3

Browse files
R-Gocgmta
authored andcommitted
Docs: Recommend the standard git workflow
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.
1 parent 5b1eba7 commit 71c8ee3

File tree

1 file changed

+20
-8
lines changed

1 file changed

+20
-8
lines changed

Documentation/GettingStartedContributing.md

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
# Getting started contributing to Ladybird
2+
23
Welcome to the Ladybird web browser project!
34

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

67
## Getting familiar with the project
8+
79
Ladybird is a large project making use of many homegrown and third-party libraries, written primarily in C++.
810

911
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
1517
The [Discord server](https://discord.gg/nvfjVJ4Svh) is the preferred way to get in contact with the maintainers and community.
1618

1719
## Getting familiar with browser engineering in general
20+
1821
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.
1922

2023
## Building the code
24+
2125
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.
2226

2327
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.
2428

2529
## Finding bugs and other issues
30+
2631
Here are some of the ways you can find an issue in Ladybird:
2732

2833
* 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
4146
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.
4247

4348
## Submitting an issue
49+
4450
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.
4551

4652
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.
4753

4854
## Submitting your code
55+
4956
### Getting familiar with C++
57+
5058
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.
5159

5260
### Getting familiar with the codebase
61+
5362
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.
5463

5564
Developer documentation:
@@ -60,34 +69,37 @@ Developer documentation:
6069
* [String formatting](StringFormatting.md)
6170

6271
### Using `git`
63-
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:
72+
73+
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:
74+
6475
```sh
65-
git remote add myfork git@github.com:MyUsername/ladybird.git
76+
git remote add upstream git@github.com:LadybirdBrowser/ladybird.git
6677
```
6778

6879
You can then create a new branch and start making changes to the code:
80+
6981
```sh
70-
git checkout -b mybranch
82+
git switch -c mybranch
7183
```
7284

7385
And finally push the commits to your fork:
86+
7487
```sh
75-
# ONLY run this the first time you push
76-
git push --set-upstream myfork mybranch
77-
# This will work for further pushes
7888
git push
7989
```
8090

8191
If you wish to sync your branch with master, or locally resolve merge conflicts, use:
92+
8293
```sh
8394
# On mybranch
84-
git fetch origin
85-
git rebase master
95+
git fetch upstream
96+
git rebase upstream/master
8697
```
8798

8899
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.
89100

90101
### Creating a pull request
102+
91103
Make sure your code meets the requirements in the [full contribution guidelines](/CONTRIBUTING.md) and [coding style](CodingStyle.md). Additionally:
92104

93105
* Make correctly formatted, atomic commits (building the project at every commit should succeed).

0 commit comments

Comments
 (0)