Everywhere: Update contribution guidelines
We've closed down the public PR route: https://ladybird.org/posts/changing-how-we-develop-ladybird/ Update our guidelines and documentation to reflect this.
This commit is contained in:
Jelle Raaijmakers
parent
50892d7370
commit
168ecb2e7d
8 changed files with 149 additions and 226 deletions
8
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
8
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
|
|
@ -97,14 +97,6 @@ body:
|
|||
attributes:
|
||||
label: Build flags or config settings
|
||||
description: If you’re building with any non-default build flags or other non-default config settings in your environment, list them out below.
|
||||
- type: checkboxes
|
||||
id: will-patch
|
||||
attributes:
|
||||
label: Contribute a patch?
|
||||
description: |
|
||||
If you plan to contribute a patch for this issue yourself, please check the box below — to tell us and others looking at the issue that someone’s already working on it. If you do check this box, please try to send a pull request within 7 days or so.
|
||||
options:
|
||||
- label: I’ll contribute a patch for this myself.
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
|
|
|
|||
4
.github/ISSUE_TEMPLATE/config.yml
vendored
4
.github/ISSUE_TEMPLATE/config.yml
vendored
|
|
@ -9,6 +9,6 @@ contact_links:
|
|||
- name: Read our documentation
|
||||
url: https://github.com/LadybirdBrowser/ladybird/blob/master/Documentation/README.md
|
||||
about: Read the docs about building Ladybird, and about configuring your Ladybird development environment.
|
||||
- name: Contribute to Ladybird
|
||||
- name: Get involved with Ladybird
|
||||
url: https://github.com/LadybirdBrowser/ladybird/blob/master/CONTRIBUTING.md
|
||||
about: Read about how you can get started contributing to Ladybird.
|
||||
about: Read the project participation guidelines.
|
||||
|
|
|
|||
164
CONTRIBUTING.md
164
CONTRIBUTING.md
|
|
@ -1,12 +1,12 @@
|
|||
# Contributing to Ladybird
|
||||
# Participating in Ladybird
|
||||
|
||||
When contributing to Ladybird, make sure that the changes you wish to make are in line with the project direction. If you are not sure about this, open an issue first, so we can discuss it.
|
||||
Ladybird is developed by a group of project maintainers, who introduce all changes to the codebase. We do not accept
|
||||
pull requests from non-maintainers and do not allow code change proposals through any other route.
|
||||
|
||||
**For your first couple of PRs, start with something small to get familiar with the project and its development processes. Please do not start by adding a large component.**
|
||||
Your involvement still matters: clear bug reports, reductions, website testing, standards discussion, design discussion,
|
||||
security reports, and technical feedback all help move the project forward.
|
||||
|
||||
Read [the Ladybird documentation](https://github.com/LadybirdBrowser/ladybird/tree/master/Documentation), including the documents in the **Development** section of the `Documentation/README.md` file.
|
||||
|
||||
Everyone is welcome to work on the project, and while we have lots of fun, it's a serious kind of fun. :^)
|
||||
Read [the Ladybird documentation](https://github.com/LadybirdBrowser/ladybird/tree/master/Documentation) if you'd like to understand how Ladybird works.
|
||||
|
||||
## Communication
|
||||
|
||||
|
|
@ -25,21 +25,6 @@ Please file any bugs you find, keeping the following in mind:
|
|||
|
||||
The Ladybird project is driven by the [Ladybird Browser Initiative](https://ladybird.org/), a 501(c)(3) non-profit organization.
|
||||
|
||||
Pull requests are approved and merged by a group of maintainers. The current group of maintainers are (in alphabetical order):
|
||||
|
||||
- [Ali Mohammad Pur (@alimpfard)](https://github.com/alimpfard)
|
||||
- [Aliaksandr Kalenik (@kalenikaliaksandr)](https://github.com/kalenikaliaksandr)
|
||||
- [Andreas Kling (@awesomekling)](https://github.com/awesomekling)
|
||||
- [Andrew Kaster (@ADKaster)](https://github.com/ADKaster)
|
||||
- [Dániel Bertalan (@BertalanD)](https://github.com/BertalanD)
|
||||
- [Gregory Bertilson (@Zaggy1024)](https://github.com/Zaggy1024)
|
||||
- [Jelle Raaijmakers (@GMTA)](https://github.com/gmta)
|
||||
- [Luke Wilde (@Lubrsi)](https://github.com/Lubrsi)
|
||||
- [Sam Atkins (@AtkinsSJ)](https://github.com/AtkinsSJ)
|
||||
- [Shannon Booth (@shannonbooth)](https://github.com/shannonbooth)
|
||||
- [Tim Flynn (@trflynn89)](https://github.com/trflynn89)
|
||||
- [Tim Ledbetter (@tcl3)](https://github.com/tcl3)
|
||||
|
||||
## Human language policy
|
||||
|
||||
In Ladybird, we treat human language as seriously as we do programming language.
|
||||
|
|
@ -55,152 +40,21 @@ The following applies to all user-facing strings, code, comments, and commit mes
|
|||
|
||||
Note that this also applies to debug logging and other internal strings, as they may be exposed to users in the future.
|
||||
|
||||
## Testing policy
|
||||
|
||||
When possible, please include tests when fixing bugs or adding new features.
|
||||
|
||||
If changes you’re making have relevant [Web Platform Tests (WPT)](https://wpt.fyi/) tests — especially if the changes cause Ladybird to pass any WPT tests it hadn’t yet been passing — you should consider [importing those tests into your Ladybird clone](https://github.com/LadybirdBrowser/ladybird/blob/master/Documentation/Testing.md#importing-web-platform-tests), and then commit the imported tests along with your code changes.
|
||||
|
||||
## Code submission policy
|
||||
|
||||
Nobody is perfect, and sometimes we mess things up. That said, here are some good do's & don'ts to try and stick to:
|
||||
|
||||
**Do:**
|
||||
|
||||
* Write in idiomatic project-style C++23, using the `AK` containers in all code.
|
||||
* Conform to the project coding style found in [CodingStyle.md](https://github.com/LadybirdBrowser/ladybird/blob/master/Documentation/CodingStyle.md). Use `clang-format` to automatically format C++ files.
|
||||
* Choose expressive variable, function and class names. Make it as obvious as possible what the code is doing.
|
||||
* Split your changes into separate, atomic commits (i.e. A commit per feature or fix, where the build, tests and the system are all functioning).
|
||||
* Make sure your commits are rebased on the master branch.
|
||||
* Wrap your commit messages at 72 characters.
|
||||
* The first line of the commit message is the subject line, and must have the format "Category: Brief description of what's being changed". The category should be the name of a library, application, service, utility, etc.
|
||||
* Examples: `LibMedia`, `WebContent`, `CI`, `AK`, `RequestServer`, `js`
|
||||
* Don't use a category like "`Libraries`" or "`Utilities`", except for generic changes that affect a large portion of code within these directories.
|
||||
* Don't use specific component names, e.g. C++ class names, as the category either - mention them in the summary instead. E.g. `LibGUI: Brief description of what's being changed in FooWidget` rather than `FooWidget: Brief description of what's being changed`
|
||||
* Several categories may be combined with `+`, e.g. `LibJS+LibWeb+Browser: ...`
|
||||
* Write the commit message subject line in the imperative mood ("Foo: Change the way dates work", not "Foo: Changed the way dates work").
|
||||
* Write your commit messages in proper English, with care and punctuation.
|
||||
* Amend your existing commits when adding changes after a review, where relevant.
|
||||
* Mark each review comment as "resolved" after pushing a fix with the requested changes.
|
||||
* Add your personal copyright line to files when making substantive changes. (Optional but encouraged!)
|
||||
* Check the spelling of your code, comments and commit messages.
|
||||
* If you have images that go along with your code, run `optipng -strip all` on them to optimize and strip away useless metadata - this can reduce file size from multiple kilobytes to a couple hundred bytes.
|
||||
|
||||
**Don't:**
|
||||
|
||||
* Submit changes that are incompatible with the project licence (2-clause BSD.)
|
||||
* Touch anything outside the stated scope of the PR.
|
||||
* Iterate excessively on your design across multiple commits.
|
||||
* Use weasel-words like "refactor" or "fix" to avoid explaining what's being changed.
|
||||
* End commit message subject lines with a period.
|
||||
* Include commented-out code.
|
||||
* Write in C. (Instead, take advantage of C++'s amenities, and don't limit yourself to the standard C library.)
|
||||
* Attempt large architectural changes until you are familiar with the system and have worked on it for a while.
|
||||
* Engage in excessive "feng shui programming" by moving code around without quantifiable benefit.
|
||||
* Add jokes or other "funny" things to user-facing parts of the system.
|
||||
|
||||
## On usage of AI and LLMs
|
||||
|
||||
Usage of AI assistance is usually fine, but you are responsible for making sure the quality of the output is up to the
|
||||
standards of the project. Currently, AI-generated output is often too verbose and its quality is subpar compared to what
|
||||
most human contributors produce.
|
||||
|
||||
Do not use an AI or LLM to generate changes, respond to issues or interact with PRs without holding the output to the
|
||||
same standards as human-written content.
|
||||
|
||||
Do not submit PRs with descriptions entirely generated by AI. Such PR descriptions are overly verbose and do not
|
||||
demonstrate that the human submitter understands the proposed changes.
|
||||
|
||||
## Pull Request Q&A
|
||||
|
||||
### I've submitted a PR and it passes CI. When can I expect to get some review feedback?
|
||||
|
||||
While unadvertised PRs may get randomly merged by curious maintainers, you will have a much smoother time if you engage with the community on Discord.
|
||||
|
||||
### If my PR isn't getting attention, how long should I wait before pinging one of the project maintainers?
|
||||
|
||||
Ping them right away if it's something urgent! If it's less urgent, advertise your PR on Discord (`#code-review`) and ask if someone could review it.
|
||||
|
||||
### Is there a policy for branches/PRs that haven't been touched in X days? Should they be closed?
|
||||
|
||||
Yes, we have a "stalebot" that will mark untouched PRs as "stale" after 21 days, and close them after another 7 days if nothing happens.
|
||||
|
||||
### Are there specific people to reach out to for different subsystems (e.g. Networking, GUI, CSS, etc)?
|
||||
|
||||
In theory, the best person to speak with is whoever wrote most code adjacent to what you're working on. In practice, asking in one of the development channels on Discord is usually easier/better, since that allows many people to join the discussion.
|
||||
|
||||
### Is Discord the place to ask for review help, or is GitHub preferred?
|
||||
|
||||
It's definitely better to ask on Discord. Due to the volume of GitHub notifications, many of us turn them off and rely on Discord for learning about review requests.
|
||||
|
||||
## Commit Hooks
|
||||
|
||||
The repository contains a file called `.pre-commit-config.yaml` that defines several 'commit hooks' that can be run automatically just before and after creating a new commit. These hooks lint your commit message, and the changes it contains to ensure they will pass the automated CI for pull requests.
|
||||
To enable these hooks firstly follow the installation instructions available at https://pre-commit.com/#install and then enable one or both of the following hooks:
|
||||
- pre-commit hook - Runs Meta/lint-ci.sh and Meta/lint-ports.py to ensure changes to the code will pass linting:
|
||||
```console
|
||||
pre-commit install
|
||||
```
|
||||
- post-commit hook - Lints the commit message to ensure it will pass the commit linting:
|
||||
```console
|
||||
pre-commit install --hook-type commit-msg
|
||||
```
|
||||
|
||||
## Git Notes
|
||||
|
||||
The GitHub project contains [git notes](https://git-scm.com/docs/git-notes) for each commit that includes e.g. a link to
|
||||
the pull request from which the commit originated and reviewer information. These are updated automatically, but require
|
||||
an additional step locally to be able to see the notes in `git log`:
|
||||
|
||||
```bash
|
||||
git config --add remote.upstream.fetch '+refs/notes/*:refs/notes/*'
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> The `upstream` remote in this command should be replaced with whatever you've named the LadybirdBrowser/ladybird.git
|
||||
> remote in your local clone. Use `git remote -v` to find that name.
|
||||
|
||||
Now, any time you `git fetch`, the latest notes will be fetched as well. You will see information like the following when
|
||||
you run `git log`:
|
||||
|
||||
```
|
||||
commit c1b0e180ba64d2ea7e815e2c2e93087ae9a26500
|
||||
Author: Timothy Flynn <trflynn89@pm.me>
|
||||
Date: Mon Jul 29 10:18:25 2024 -0400
|
||||
|
||||
LibWebView: Insert line numbers before each line in about:srcdoc
|
||||
|
||||
The behavior chosen here (fixed-width counters, alignment, etc.) matches
|
||||
Firefox.
|
||||
|
||||
Notes:
|
||||
Author: https://github.com/trflynn89
|
||||
Commit: https://github.com/LadybirdBrowser/ladybird/commit/c1b0e180ba6
|
||||
Pull-request: https://github.com/LadybirdBrowser/ladybird/pull/892
|
||||
Reviewed-by: https://github.com/AtkinsSJ ✅
|
||||
```
|
||||
|
||||
## On abandoned pull requests
|
||||
|
||||
Sometimes good PRs get abandoned by the author for one reason or another. If the PR is fundamentally good, but the author is not responding to requests, the PR may be manually integrated with minor changes to code and commit messages.
|
||||
|
||||
To make this easier, we do appreciate it if folks enable the "Allow edits from maintainers" flag on their pull requests.
|
||||
|
||||
## On neutrality
|
||||
|
||||
Our goal is to build a browser for everyone, irrespective of their specific opinions and worldviews.
|
||||
To achieve this, we strive to set our differences aside and focus on the shared goal of building the browser.
|
||||
|
||||
This means:
|
||||
- We welcome contributions from anyone who is committed to the project's goals and respects the collaborative environment.
|
||||
- We welcome involvement from anyone who is committed to the project's goals and respects the collaborative environment.
|
||||
- Our discussions and work will remain strictly related to browser development and web standards. We do not take positions on issues outside this scope.
|
||||
- The project will not be used as a platform to advertise or promote causes unrelated to browser development or web standards.
|
||||
- To maintain a focused and productive environment, discussions on societal politics and other divisive topics are discouraged in project spaces.
|
||||
|
||||
We encourage everyone to share their personal views and opinions outside project spaces. However, please keep project spaces focused on project goals.
|
||||
We encourage everyone to share their personal views and opinions outside project spaces, so we can keep them focused on project goals.
|
||||
|
||||
## On bad-faith contributions and brigading
|
||||
|
||||
We reserve the right to reject issues and pull requests that appear to be motivated by bad faith.
|
||||
We reserve the right to reject issues and other interactions that appear to be motivated by bad faith.
|
||||
|
||||
Additionally, anyone found participating in social media brigading of Ladybird will be permanently banned from the project.
|
||||
|
|
|
|||
119
Documentation/CodePolicy.md
Normal file
119
Documentation/CodePolicy.md
Normal file
|
|
@ -0,0 +1,119 @@
|
|||
# Code Policy
|
||||
|
||||
This document describes expectations for code maintained in upstream Ladybird. It is primarily intended for project maintainers and people studying local Ladybird development.
|
||||
|
||||
## Testing policy
|
||||
|
||||
When possible, code changes should include tests when fixing bugs or adding new features.
|
||||
|
||||
If changes have relevant [Web Platform Tests (WPT)](https://wpt.fyi/) tests - especially if the changes cause Ladybird to pass any WPT tests it had not yet been passing - consider [importing those tests into the Ladybird tree](Testing.md#importing-web-platform-tests), and then committing the imported tests along with the code changes.
|
||||
|
||||
## Human language policy
|
||||
|
||||
In Ladybird, we treat human language as seriously as we do programming language.
|
||||
|
||||
The following applies to all user-facing strings, code, comments, and commit messages:
|
||||
|
||||
* 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.
|
||||
|
||||
Note that this also applies to debug logging and other internal strings, as they may be exposed to users in the future.
|
||||
|
||||
## Code policy
|
||||
|
||||
Nobody is perfect, and sometimes we mess things up. That said, here are some good do's & don'ts to try and stick to:
|
||||
|
||||
**Do:**
|
||||
|
||||
* Write in idiomatic project-style C++23, using the `AK` containers in all code.
|
||||
* Conform to the project coding style found in [CodingStyle.md](CodingStyle.md). Use `clang-format` to automatically format C++ files.
|
||||
* Choose expressive variable, function and class names. Make it as obvious as possible what the code is doing.
|
||||
* Split your changes into separate, atomic commits (i.e. A commit per feature or fix, where the build, tests and the system are all functioning).
|
||||
* Make sure your commits are rebased on the master branch.
|
||||
* Wrap your commit messages at 72 characters.
|
||||
* The first line of the commit message is the subject line, and must have the format "Category: Brief description of what's being changed". The category should be the name of a library, application, service, utility, etc.
|
||||
* Examples: `LibMedia`, `WebContent`, `CI`, `AK`, `RequestServer`, `js`
|
||||
* Don't use a category like "`Libraries`" or "`Utilities`", except for generic changes that affect a large portion of code within these directories.
|
||||
* Don't use specific component names, e.g. C++ class names, as the category either - mention them in the summary instead. E.g. `LibGUI: Brief description of what's being changed in FooWidget` rather than `FooWidget: Brief description of what's being changed`
|
||||
* Several categories may be combined with `+`, e.g. `LibJS+LibWeb+Browser: ...`
|
||||
* Write the commit message subject line in the imperative mood ("Foo: Change the way dates work", not "Foo: Changed the way dates work").
|
||||
* Write your commit messages in proper English, with care and punctuation.
|
||||
* Amend existing commits when adding changes after a review, where relevant.
|
||||
* Mark each review comment as "resolved" after pushing a fix with the requested changes, where relevant.
|
||||
* Add your personal copyright line to files when making substantive changes. (Optional but encouraged!)
|
||||
* Check the spelling of your code, comments and commit messages.
|
||||
* If you have images that go along with your code, run `optipng -strip all` on them to optimize and strip away useless metadata - this can reduce file size from multiple kilobytes to a couple hundred bytes.
|
||||
|
||||
**Don't:**
|
||||
|
||||
* Introduce changes that are incompatible with the project licence (2-clause BSD.)
|
||||
* Touch anything outside the stated scope of the change.
|
||||
* Iterate excessively on your design across multiple commits.
|
||||
* Use weasel-words like "refactor" or "fix" to avoid explaining what's being changed.
|
||||
* End commit message subject lines with a period.
|
||||
* Include commented-out code.
|
||||
* Write in C. (Instead, take advantage of C++'s amenities, and don't limit yourself to the standard C library.)
|
||||
* Attempt large architectural changes until you are familiar with the system and have worked on it for a while.
|
||||
* Engage in excessive "feng shui programming" by moving code around without quantifiable benefit.
|
||||
* Add jokes or other "funny" things to user-facing parts of the system.
|
||||
|
||||
## On usage of AI and LLMs
|
||||
|
||||
Usage of AI assistance is usually fine, but you are responsible for making sure the quality of the output is up to the standards of the project. Currently, AI-generated output is often too verbose and its quality is subpar compared to carefully written human work.
|
||||
|
||||
Do not use an AI or LLM to generate changes, respond to issues, or participate in project discussion without holding the output to the same standards as human-written content.
|
||||
|
||||
Do not use AI-generated descriptions or summaries as a substitute for understanding the relevant code, issue, or discussion.
|
||||
|
||||
## Commit hooks
|
||||
|
||||
The repository contains a file called `.pre-commit-config.yaml` that defines several commit hooks that can be run automatically just before and after creating a new commit. These hooks lint your commit message, and the changes it contains to ensure they will pass the automated CI checks.
|
||||
|
||||
To enable these hooks, first follow the installation instructions available at https://pre-commit.com/#install and then enable one or both of the following hooks:
|
||||
|
||||
* pre-commit hook - Runs `Meta/lint-ci.sh` and `Meta/lint-ports.py` to ensure changes to the code will pass linting:
|
||||
|
||||
```console
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
* post-commit hook - Lints the commit message to ensure it will pass the commit linting:
|
||||
|
||||
```console
|
||||
pre-commit install --hook-type commit-msg
|
||||
```
|
||||
|
||||
## Git notes
|
||||
|
||||
The GitHub project contains [git notes](https://git-scm.com/docs/git-notes) for each commit that includes e.g. a link to the pull request from which the commit originated and reviewer information. These are updated automatically, but require an additional step locally to be able to see the notes in `git log`:
|
||||
|
||||
```bash
|
||||
git config --add remote.upstream.fetch '+refs/notes/*:refs/notes/*'
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> The `upstream` remote in this command should be replaced with whatever you've named the LadybirdBrowser/ladybird.git
|
||||
> remote in your local clone. Use `git remote -v` to find that name.
|
||||
|
||||
Now, any time you `git fetch`, the latest notes will be fetched as well. You will see information like the following when you run `git log`:
|
||||
|
||||
```
|
||||
commit c1b0e180ba64d2ea7e815e2c2e93087ae9a26500
|
||||
Author: Timothy Flynn <trflynn89@pm.me>
|
||||
Date: Mon Jul 29 10:18:25 2024 -0400
|
||||
|
||||
LibWebView: Insert line numbers before each line in about:srcdoc
|
||||
|
||||
The behavior chosen here (fixed-width counters, alignment, etc.) matches
|
||||
Firefox.
|
||||
|
||||
Notes:
|
||||
Author: https://github.com/trflynn89
|
||||
Commit: https://github.com/LadybirdBrowser/ladybird/commit/c1b0e180ba6
|
||||
Pull-request: https://github.com/LadybirdBrowser/ladybird/pull/892
|
||||
Reviewed-by: https://github.com/AtkinsSJ ✅
|
||||
```
|
||||
|
|
@ -13,7 +13,7 @@ Ladybird is pre-alpha software you have to build from the sources yourself in or
|
|||
|
||||
## Windows support when?
|
||||
|
||||
There are very few Windows developers contributing to the project. As such, maintaining a native Windows port would be
|
||||
There are very few maintainers working on Windows support. As such, maintaining a native Windows port would be
|
||||
a lot of effort that distracts from building out the web platform standards in a reasonable amount of time.
|
||||
|
||||
After we have a solid foundation, we may consider a Windows port, but it's not a priority. In the meantime, Windows
|
||||
|
|
@ -25,7 +25,8 @@ Eventually, probably, if there's a Web Spec for it!
|
|||
|
||||
## When will you implement `$THING`?
|
||||
|
||||
Maybe someday. Maybe never. If you want to see something happen, you can do it yourself!
|
||||
There's no concrete roadmap of individual features yet. You can always raise an issue so we can keep track, if one does
|
||||
not already exist!
|
||||
|
||||
### Will you have a built in ad blocker?
|
||||
|
||||
|
|
@ -86,7 +87,7 @@ Here’s a short timeline:
|
|||
- Prove that developing an engine doesn’t take hundreds of engineers — and not anything close to even just a hundred.
|
||||
- Browser engineering: Further help de-mystify it and make it a standard thing to learn (hat tip: https://browser.engineering/).
|
||||
- Using project Discord server for communication [discord.gg/nvfjVJ4Svh](https://discord.gg/nvfjVJ4Svh).
|
||||
- Using [one GithHub repo](https://github.com/LadybirdBrowser/ladybird) for everything: issues (no bugzilla or other), patch/PR submission/review, CI/test automation.
|
||||
- Using [one GitHub repo](https://github.com/LadybirdBrowser/ladybird) for issues, CI, and test automation.
|
||||
|
||||
## What are some of the project coding conventions? And do you have any activity metrics?
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# Getting started contributing to Ladybird
|
||||
# Getting involved with 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.
|
||||
This document is a beginner-friendly guide to getting familiar with Ladybird and helping the project through testing, bug reports, reductions, standards discussion, design discussion, security reports, and technical feedback.
|
||||
|
||||
## Getting familiar with the project
|
||||
|
||||
|
|
@ -32,30 +32,26 @@ Here are some of the ways you can find an issue in Ladybird:
|
|||
|
||||
* By checking the [issue tracker](https://github.com/LadybirdBrowser/ladybird/issues).
|
||||
* Manually, by using the browser as you normally would.
|
||||
* By finding failing WPT tests on [WPT.fyi](https://wpt.fyi/results/?label=master&product=ladybird). Note that while fixes are welcome, you don't need to submit issue reports for individual tests.
|
||||
* By finding failing WPT tests on [WPT.fyi](https://wpt.fyi/results/?label=master&product=ladybird). You do not need to submit issue reports for individual tests.
|
||||
* By finding WPT tests on [WPT.fyi](https://wpt.fyi/results/?label=master&product=ladybird) that are [timing out in Ladybird](https://wpt.fyi/results/?product=ladybird&q=status%3Atimeout). 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()”](https://www.youtube.com/watch?v=X4S9afzRTXs) “browser hacking” video.
|
||||
* By using a profiling tool such as [Callgrind](https://valgrind.org/docs/manual/cl-manual.html) to find code that can be improved.
|
||||
* By looking for [`TODO`](https://github.com/search?q=repo%3ALadybirdBrowser%2Fladybird%20%22%2F%2F%20TODO%22&type=code) and [`FIXME`](https://github.com/search?q=repo%3ALadybirdBrowser%2Fladybird+%22%2F%2F+FIXME%22&type=code) comments in the codebase.
|
||||
|
||||
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.
|
||||
If you’re not necessarily fluent in C++, beginning by troubleshooting WPT tests may be the very best way to get started helping 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.
|
||||
|
||||
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.
|
||||
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. That alone can be a very big help to maintainers and other people investigating the related C++ code.
|
||||
|
||||
## 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.
|
||||
|
||||
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 [project participation 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
|
||||
## Learning the codebase
|
||||
|
||||
### 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.
|
||||
|
||||
### Getting familiar with the codebase
|
||||
|
||||
|
|
@ -67,42 +63,3 @@ Developer documentation:
|
|||
* [Coding patterns](Patterns.md)
|
||||
* [Smart pointers](SmartPointers.md)
|
||||
* [String formatting](StringFormatting.md)
|
||||
|
||||
### Using `git`
|
||||
|
||||
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
|
||||
git remote add upstream git@github.com:LadybirdBrowser/ladybird.git
|
||||
```
|
||||
|
||||
You can then create a new branch and start making changes to the code:
|
||||
|
||||
```sh
|
||||
git switch -c mybranch
|
||||
```
|
||||
|
||||
And finally push the commits to your fork:
|
||||
|
||||
```sh
|
||||
git push
|
||||
```
|
||||
|
||||
If you wish to sync your branch with master, or locally resolve merge conflicts, use:
|
||||
|
||||
```sh
|
||||
# On mybranch
|
||||
git fetch upstream
|
||||
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.
|
||||
|
||||
### 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 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](Testing.md#importing-web-platform-tests))
|
||||
|
|
|
|||
|
|
@ -1,8 +1,7 @@
|
|||
# Ladybird Documentation
|
||||
|
||||
Ladybird development moves quickly, so some of these might be out of date. Please let us know if something here is wrong,
|
||||
or submit a PR with any additions or corrections! If you have any questions that are not answered here or in the [FAQ](FAQ.md),
|
||||
you are welcome to ask on [Discord](../README.md#get-in-touch-and-participate).
|
||||
Ladybird development moves quickly, so some of these might be out of date. Please let us know if something here is wrong.
|
||||
If you have any questions that are not answered here or in the [FAQ](FAQ.md), you are welcome to ask on [Discord](../README.md#get-in-touch-and-participate).
|
||||
|
||||
## Building and Running
|
||||
* [Build Instructions](BuildInstructionsLadybird.md)
|
||||
|
|
@ -22,7 +21,8 @@ you are welcome to ask on [Discord](../README.md#get-in-touch-and-participate).
|
|||
* [VS Code](EditorConfiguration/VSCodeConfiguration.md)
|
||||
|
||||
## Development
|
||||
* [How to Contribute](../CONTRIBUTING.md)
|
||||
* [Project Participation](../CONTRIBUTING.md)
|
||||
* [Code Policy](CodePolicy.md)
|
||||
* [Coding Style](CodingStyle.md)
|
||||
* [Common Patterns](Patterns.md)
|
||||
* [Guidelines for Text in UI](HumanInterfaceGuidelines/Text.md)
|
||||
|
|
|
|||
|
|
@ -41,13 +41,13 @@ Code-related documentation can be found in the [documentation](Documentation/) f
|
|||
|
||||
## Get in touch and participate!
|
||||
|
||||
Join [our Discord server](https://discord.gg/nvfjVJ4Svh) to participate in development discussion.
|
||||
Join [our Discord server](https://discord.gg/nvfjVJ4Svh) to participate in issue and development discussions.
|
||||
|
||||
Please read [Getting started contributing](Documentation/GettingStartedContributing.md) if you plan to contribute to Ladybird for the first time.
|
||||
Please read [Getting involved with Ladybird](Documentation/GettingStartedContributing.md) if you're new to Ladybird and want to help.
|
||||
|
||||
Before opening an issue, please see the [issue policy](CONTRIBUTING.md#issue-policy) and the [detailed issue-reporting guidelines](ISSUES.md).
|
||||
|
||||
The full contribution guidelines can be found in [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
The project participation guidelines can be found in [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue