Skip to content

Commit 430754d

Browse files
Mard0cMard0c
committed
Documentation: Revised ISSUES.md
1 parent 2db3796 commit 430754d

File tree

1 file changed

+65
-45
lines changed

1 file changed

+65
-45
lines changed

‎ISSUES.md‎

Lines changed: 65 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,96 @@
1-
# Issue-reporting guidelines
1+
# Issues: Hunting Down Unexpected Behaviours
22

3-
Report problems using our detailed [bug-reporting
4-
form](https://github.com/LadybirdBrowser/ladybird/issues/new?template=bug_report.yml), which helps to ensure that, for us to reproduce and investigate the problem, your bug report includes the information needed — including a reduced test case.
3+
Browsers have an enormous number of edge cases, if you can find one, and isolate exactly where the unexpected behaviour is coming from, that can already help a lot!
54

6-
## How you can write a reduced test case
5+
That's where reduced test cases and issue raising comes in. By the end of this guide you'll know how to isolate an unexpected behaviour in a reduced test case, and you'll know where, when, and how to raise an issue.
76

8-
When raising an issue, the single-most important thing you can provide is a reduced test others can use to reproduce the problem.
7+
>[!CAUTION]
8+
> - No build issues (or other support requests). If the GitHub Actions CI build succeeds, the build problem is most likely on your side. Work it out locally, or ask in the `#build-problems` channel on Discord. Do not create an issue.
9+
> - One bug per issue. Putting multiple things in the same issue makes both discussion and completion unnecessarily complicated.
10+
>- Don't comment on issues just to add a joke or irrelevant commentary. Hundreds of people get notified about comments so let's keep them relevant.
11+
>- If you can't to reduce the test case (see bellow), please go to the discord before raising an issue!
912
10-
You can create a reduced test case for a problem by starting from the HTML/JS/CSS source for a particular website/page which causes the problem, and removing as much content as possible while still having a document that reproduces the problem.
13+
If you've been here before and you're just looking for the link to the form, [here it is](https://github.com/LadybirdBrowser/ladybird/issues/new?template=bug_report.yml).
1114

12-
Here’s how you can do that:
15+
>[!NOTE]
16+
> The following guide assumes:
17+
> - You have some web development knowledge (comfortable in the inspector).
18+
> - You have followed the [getting started guide]() (ladybird is running on your device).
19+
> - You have joined the discord server.
1320
14-
1. Create a local `REDUCTION.html` (or whatever name) copy of the page — ideally by using something like the [SingleFile](https://addons.mozilla.org/en-US/firefox/addon/single-file/) extension for Firefox or Chrome to save a canned copy of the page as it currently exists (post-JS-execution).
21+
Ladybird developers are looking for reduced test cases;
22+
the simplest code that can reproduce **_just one_** unexpected behaviour.
1523

16-
That also allows you to use Firefox/Chrome devtools to quickly strip out irrelevant elements from the page before saving a copy.
1724

18-
2. If you’re *not* using something like SingleFile, then: To ensure any images,external style sheets, or external scripts that use a relative path will get loaded by your local `REDUCTION.html` document, put a `base` element into the document — like this:
25+
# How to Reduce the Test Case
26+
Put very plainly, your aim is to keep removing things until only the source of the unexpected behaviour is left.
1927

20-
```html
21-
<base href="https://ladybird.org/">
22-
```
28+
```mermaid
29+
flowchart LR
2330
24-
However, if the problem appears to be caused not by anything in the source of the document itself, but instead by something in an external script or external stylesheet, then you’ll also need to create a local copy of the problem script or problem stylesheet.
31+
A[Find behaviour] --> B{Use SingleFile?}
2532
26-
3. Open/load the `REDUCTION.html` file in Ladybird, and verify that the same problem occurs with it as occurs with the original website/page you copied it from.
33+
B -->|Yes| C[Capture & clean with SingleFile]
34+
B -->|No| D[Put needed content & resources<br>into one .html]
2735
28-
4. **Script-related problems:** Especially if you believe the problem is related to any JavaScript that the document is executing, then temporarily disable scripting by unchecking **Enable Scripting** option in the **Debug** menu in Ladybird, and then reload the `REDUCTION.html` file in Ladybird.
36+
C --> E[Load .html in Ladybird]
37+
D --> E
2938
30-
* If the problem still happens after you’ve disabled scripting, then you can remove any and all `script` elements from the document, and you can continue on from there.
39+
E --> F{Does the error still occur?}
3140
32-
* If the problem does not happen any longer after you’ve disabled scripting, then that tells you the cause is related to the contents from one or more of the `script` elements, and you can check the **Enable Scripting** option to turn scripting back on, and you can continue on from there.
41+
F -->|No| H[Include more] --> E
42+
F -->|Yes| G[Remove content]
3343
34-
5. **CSS-related problems**: Especially if you believe that the problem is related to any CSS stylesheets the document is using, then:
44+
G --> I{Does behaviour persist?}
3545
36-
1. [If you’ve not used something like the [SingleFile](https://addons.mozilla.org/en-US/firefox/addon/single-file/) extension for Firefox or Chrome] Add a `style` element in the `REDUCTION.html` file, and then for each external style sheet the document has, paste the contents from that external stylesheet into that `style` element.
37-
38-
2. Start removing CSS rules from any and all `style` elements in the document, and reload the `REDUCTION.html` file in Ladybird.
39-
40-
* If the problem does not happen any longer after you’ve removed a particular CSS rule, then you may have isolated the cause. Re-add that CSS rule to the document, and continue on from there.
41-
42-
* If the problem does continue to happen after you’ve removed a CSS rule, then you’ve successfully reduced the test case by one CSS rule, and you can continue on from there.
46+
I -->|Yes| J[You found a culprit!]
47+
I -->|No| G
48+
```
49+
1. Find a behaviour on a web page in ladybird that isn't what you'd expect in Chrome/Firefox.
4350

44-
Either way, keep repeating the two steps above, removing CSS rules one by one, and with each removal, checking whether the problem still happens — and if it does, putting the CSS rule you removed back into the document, or otherwise, leaving the CSS rule out and moving on.
51+
2. Get a .html file (eg. REDUCTION.html) containing your unexpected behaviour.
4552

46-
6. **HTML-related problems:** Begin removing one *element* at time from the `REDUCTION.html` file, starting with the elements in the document `head`.
53+
- Often the easiest way is to open the page in Chrome/Firefox; use the [SingleFile](https://addons.mozilla.org/en-US/firefox/addon/single-file/) extension to save a canned copy of the page as it currently exists (post-JS-execution). In SingleFile you can already remove a considerable amount that probably has nothing to do with the unexpected behaviour.
4754

48-
7. Reload the `REDUCTION.html` file in Ladybird, and verify whether the problem is still happening.
55+
- If you aren't using something like SingleFile you may need external scripts, stylesheets, and/or anything else that rely on a relative path to reproduce the behaviour. Either:
56+
- paste relevant stylesheets, svgs, scripts, etc.. directly in the html document,
57+
- create a local copy of the resource,
58+
- put a [`<base>`](https://www.w3schools.com/TAGs/tag_base.asp)element in the document like this: `<base href="https://your.webpage.url/">`
4959

50-
* If the problem does not happen any longer after you’ve removed a particular element, then you may have isolated the cause. Re-add that element to the document, and continue on from there.
5160

52-
* If the problem does continue to happen after you’ve removed a particular element, then you’ve successfully reduced the test case by one element, and you can continue on from there.
61+
3. Verify that the behaviour still occurs by loading your `REDUCTION.html` file in Ladybird.
5362

54-
Either way, keep repeating the steps: removing elements one by one, and with each removal, checking whether the problem still happens — and if it does, putting the element you removed back into the document, or otherwise, leaving the element out and moving on.
63+
4. By process of elimination, you're going to find the source of the behaviour within REDUCTION.html; If the issue is in:
64+
- a **script**, then unchecking **Enable Scripting** option in the **Debug** menu in Ladybird would stop the behaviour.
65+
- a **stylesheet**, removing the rule would stop the behaviour.
66+
- the **html**, removing the element would stop the behaviour.
67+
So just keep removing anything that doesn't stop the behaviour and eventually all you'll have left are the culprits of the one unexpected behaviour.
5568

56-
In the end, after following the steps above and removing elements and CSS rules, you’ll have a reduced test case that you can include when you raise an issue for the problem.
69+
To pinpoint the unexpected behaviour, it may be helpful to use the `--enable-idl-tracing` command-line flag when running Ladybird. This will output detailed information about the calls being made to the browser's internal interfaces.
5770

58-
## How to share/publish your reduced test case at a URL
71+
```
72+
./Meta/ladybird.py run ladybird --enable-idl-tracing
73+
```
5974

60-
You can take your reduced test case and post it online at a site such as the following:
75+
If you get stuck, remember there's very active community around you. Throw what you're stuck on in the discord, we're excited to learn what you've found so far!
6176

62-
* https://codepen.io/pen/
63-
* https://jsbin.com
64-
* https://jsfiddle.net
6577

66-
That will give you a URL which you can then include in the issue you raise for the problem.
78+
# How to Raise the Issue
79+
Once you've honed in your reduced test case,
80+
- You can share your test case at a URL using one of the following:
81+
- [https://codepen.io/pen/](https://codepen.io/pen/)
82+
- [https://jsbin.com](https://jsbin.com)
83+
- [https://jsfiddle.net](https://jsfiddle.net)
6784

68-
*[Credits: The “How you can write a reduced test case” details above are largely taken from https://webkit.org/test-case-reduction/.]*
85+
- Fill in [the bug-reporting form](https://github.com/LadybirdBrowser/ladybird/issues/new?template=bug_report.yml). Include your link or put the your reduced test case directly in the form's section titled "HTML/SVG/etc. source for a reduced test case".
6986

70-
## Debugging
87+
# Examples
88+
This might seem a little intimidating, so here are a few examples that are easy enough to follow and might serve as inspiration!
7189

72-
When investigating a bug, it can be helpful to use the `--enable-idl-tracing` command-line flag when running Ladybird. This will output detailed information about the calls being made to the browser's internal interfaces, which can help pinpoint where a problem is occurring.
90+
[issue #6193](https://github.com/LadybirdBrowser/ladybird/issues/6193)<br>
91+
[issue #6085](https://github.com/LadybirdBrowser/ladybird/issues/6085)<br>
92+
[issue #6275](https://github.com/LadybirdBrowser/ladybird/issues/6275)
7393

74-
```bash
75-
./Meta/ladybird.py run ladybird --enable-idl-tracing
76-
```
94+
# Going Further
95+
Want to patch to your issue?
96+
[Getting Started Contributing]() is your friend.

0 commit comments

Comments
 (0)