Revised ISSUES.md #6943
Revised ISSUES.md #6943
Conversation
|
Hello! One or more of the commit messages in this PR do not match the Ladybird code submission policy, please check the |
| <base href="https://ladybird.org/"> | ||
| ``` | ||
| ```mermaid | ||
| flowchart LR |
There was a problem hiding this comment.
This flow chart confuses me.
I'm not sure what "cleaning with SingleFile" would entail, and I'm not sure the SingleFile / no SingleFile distinction is super important in the flow chart.
Also, "Does the error still occur?" and "Does behaviour persist?" seem redundant and wired in a rather roundabout (maybe even incorrect) fashion.
There was a problem hiding this comment.
Couldn't agree more.
flowchart LR
A[Capture reproducible .html] --> G[Remove content]
G --> I{Does behaviour persist?}
I -->|No| J[You found a culprit!]
I -->|Yes| G
This is a better flow chart, but do we need one at all?
|
Also, all the JS-specific info seems to have gone missing in the rewrite... |
| * https://jsfiddle.net | ||
|
|
||
| That will give you a URL which you can then include in the issue you raise for the problem. | ||
| # How to Raise the Issue |
There was a problem hiding this comment.
This now lumps uploading the test case to some website in with actually opening the issue and makes it seem like a prerequisite or step 1 of 2.
Most of the time, you don't need to upload the test case to any of these sites, you can just paste it into the issue form in its entirety.
There was a problem hiding this comment.
I'm would go as far as saying we should not encourage people to use these sites at all:
- These sites are great for sharing a particular way to solve a problem and then being able to iterate on it quickly. However they are not great for reproducing browser bugs. The "shell" introduced by them is a bunch of overhead that makes things impossible to debug. So, before you can use a testcase in these sites, you must extract the actual contents back into a file, causing extra steps.
- Even worse, some of these sites encourage users to make a clean separation between HTML, CSS and JS, causing the reproduction to get split into multiple parts and doing other potentially undesirable modifications that shouldn't matter according to the specs, but might matter for a browser bug. All of these need to be undone before anyone looking to fix a bug can start debugging the problem, causing even more extra step.
- It wouldn't be the first time that such a service decides to overzealously delete especially content from anonymous users, so reproduction cases uploaded to such a service have a non-negligible chance of disappearing if they happen to only be saved on the site in question
I think instead we should encourage users to provide the reproduction inline and additionally as a base64-encoded data URI instead (like data:text/html;base64,CjwhRE9DVFlQRSBodG1sPgo8aDE+SGVsbG8gV29ybGQ8L2g+). These can be copied and pasted into the browser directly, without having to save it to a file first. That is useful for a quick check whether a problem is still reproducible or not.
|
|
||
| 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. | ||
| 4. By process of elimination, you're going to find the source of the behaviour within REDUCTION.html; If the issue is in: | ||
| - a **script**, then unchecking **Enable Scripting** option in the **Debug** menu in Ladybird would stop the behaviour. |
There was a problem hiding this comment.
| - a **script**, then unchecking **Enable Scripting** option in the **Debug** menu in Ladybird would stop the behaviour. | |
| - a **script**, then unchecking **Enable Scripting** option in the **Debug** menu in Ladybird would stop the behaviour. Dig further by progressively removing script contents. |
Also, all the JS-specific info seems to have gone missing in the rewrite...
Other than this (which I agree, was definitely missing) is there any other JS specific information missing / should be added?
5 participants
I've revised the issue reporting guidelines (ISSUES.md) as part of a university course on technical documentation.
Since Ladybird is about to go into alpha, issues will be raised at a much higher frequency with far less familiarity with the project and its norms. So a clear guide to raising useful issues seemed like an interesting contribution.
The previous document's shortcomings (imo):
I've written with 3 sorts of readers in mind:
The intrigued web developer
"I heard about ladybird, I have a background in web development and thought it might be fun to isolate an unexpected behaviour."
This is the group I see being able to contribute the most by just raising issues. They should finish reading it feeling like reducing a test case and raising the issue is very achievable.
The disgruntled browser engineer
“While working on something unrelated I found a bug and just want to raise an issue and get on with my work.”
Keeping “disgruntled engineers” in mind, it should be concise and scannable.
The excited “techy” 16 year old
"Oh I wonder how Ladybird is coming along? Can it play youtube videos yet? I'm naive enough to think I can install it."
They don’t have to be 16 obviously, but they need enough tech literacy to be excited about the alpha and enough gumption to act on the excitement but they are on the wrong side of the dunning-kruger effect.
Keeping this persona in mind pushed me to be extra clear and assume that the further down the document I wrote something, the less likely this persona would be to ever see it…
The flowchart is pretty overkill, despite having a lot of freedom with this project, I did need a diagram to get university credits for this. In the end, I think it actually gives a pretty nice overview, but I could see it removed as well.
This is my first open source contribution, so apologies if I'm a bit clumsy.