Skip to content

Instantly share code, notes, and snippets.

@karlcow
Last active January 25, 2018 04:25
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save karlcow/d5254456df9bc722edbb0512e635fc83 to your computer and use it in GitHub Desktop.
Save karlcow/d5254456df9bc722edbb0512e635fc83 to your computer and use it in GitHub Desktop.

Build Tools For Webcompat

webcompat is an opensource project. It relies on the effort of Mozilla webcompat team and contributions from volunteers across the world. Microsoft Edge team and Google Chrome team are also participating time to time.

There are different areas were you can create an impact on developing tools including:

Diagnose A Webcompat Issue

Someone has reported a bug. It has been successfully triaged. The issue is now in the needs diagnosis list. You can help!

Have A Neutral Test Environment{#neutral}

To have a successful diagnosis of the issue, you will probably need to have a setup which makes it possible to have a fresh profile of the browser you are testing with. Previous logins, addons or web extensions, changed settings are parameters which might have influence on your ability to diagnose correctly the source of the issue. For example, on firefox you can create a profile which resets which each browser restart.

Develop Competences, Have Impact{#skills}

Pick up an issue from the list and starts analyzing the reasons. You will probably spend a lot of time in the developer tools of each browser, tweaking values, inserting breakpoints in JavaScript code, reading specifications. Without realizing it, after a while, you will learn a lot about the subtle differences in between browsers.

You might end up opening an issue on one of the browser reporting systems, because you discovered something off with the core engine of the browsers (such as Gecko on Firefox, Blink on Chrome/Opera and others, and WebKit on Safari). The Web platform will be a better place because of you.

Be verbose{#verbose}

Provide as [much details as possible](@@insert link of a good analysis@@) during your analysis. Your thought process in diagnosing the issue is as important as your conclusion. It helps other people who are in charge of contacting websites and websites owners to have a better understanding of the issue. It will be quicker to negotiate a fix once all the details are known.

@@question: provide some links to more in depth articles or maybe we reference a wiki page which has the links (MDN?). This avoid to have to do pull request to adjust the list.@@

Organize A Webcompat Event

Time to time you may want to organize an event for testing Web sites with a group of friends, volunteers, etc. It can be a fun way to discuss issues and understand them. It's also a good opportunities for people to learn about new technologies. During the event, people will report issues to webcompat.com.

An event will require a bit of preparation. Here are some tips on the organization.

Before{#before}

  • Read carefully the (Report A Website Issue)[/contribute/report]
  • Understand what is and what is not a Webcompat issue.
  • You might want to create a list of websites that needs to be tested with a column for people to put their names so we can avoid duplicate testing of the same site.

During{#during}

  • Explain to participants that reports quality is the goal.
  • Help participants to create a fresh profile that they can reset at each restart of the browser.
  • Make sure that it has been tested in multiple browsers.
  • Avoid duplicates of the same issues. Too often during webcompat sprints, we close issues reported multiple times.
  • Encourage participants to write detailed steps for reproducing the issue. An idea is for example to work as a team. One finds an issue, write the form without submitting it. The team mate on another computer is trying to reproduce the issue with only the form instructions. If the person can't understand the given instructions and/or can't see where the issue is, then it's probably an incomplete report.
  • Take pictures and share them online (if participants agree). Notify us on twitter at @webcompat

After{#after}

It's not about quantity, it's about quality. We try to improve the Web. A larger number of issues might not necessary help us to fix a browser or a website faster. On the other hand, being able to followup on the issues when there are unknown details or additional questions from people triaging and diagnosing is invaluable. Reporting many issues without being able to answer questions afterward because you have no time, or you are not interested, might end up in a dead end.

You might want to do additional meetings for specifically following up on these issues. It's a great opportunity to learn how to debug and understand what is happening in a Web page.

Share with us what worked and didn't work so we can improve these guidelines.

Participate To Website Outreach

Website outreach provides a way to close on web compatibility issues requiring modifications on the website itself. Social and communication skills are key. Technicall skills may come handy but not absolutely necessary. If done well, you will help web users to have a better experience.

@@here reuse the already existing content in https://webcompat.com/contributors with new screenshots@@

Report A Website Issue

Once upon a time there was an issue on a website. Something is behaving differently in your favorite browser and not in another one. A menu is not working; the layout is a bit off; the click or tap on this link is not working. You may want to report an issue. We have tools and recommendations on detecting issues not in the scope of this project.

How To Report An Issue?{#how}

The goal of reporting an issue is to give all the possible information that will help someone without any context to understand, reproduce and eventually diagnose the symptoms of this issue.

@@insert here form screenshot@@ When reporting an issue directly on webcompat.com or through external tools, you will always end up on the webcompat form. Some of the fields in this form are mandatory. Take time to be precise and to guide us through the steps that will make it possible to reproduce the issue.

@@Show a screenshot example of a form with the correct information@@

  • The exact URL
  • A short summary helping us to understand the issue
  • Select the type of bug
  • What are the steps you went through before having the issue. Sometimes it will require you to describe the paths and actions made on the Web site in case of shopping carts not working, logins failing, etc. Don't be shy with words.
  • Modify the browser information if you are reporting an issue for another browser.
  • If possible, make sure you tested in another browser before reporting. Many site layout issues which seems to be valid are in fact design choices reproducible in every browsers. These are not webcompat issues.
  • A screenshot of the page or just the area which is failing can help a lot too. Be mindful about screenshots containing private information about yourself or others (such as social network private pages or bank sites).

You can report the issue anonymously or with your Github username. (We use GitHub issue reporting system for the webcompat.com backend). When you are identified, we can better follow-up with you if there are additional information required to understand the issue. Anonymous issues which lack details will be closed because we can't create a diagnosis.

Tools To Report An Issue{#tools}

There are basically three ways of reporting an issue depending on your browser.

The Form{#form}

The webcompat report form is the main avenue to report an issue.

Web Extensions{#webextensions}

@@find the links for Safari and Chrome@@

We do not have currently an extension for Chrome on Android and Safari on iOS, you are welcome to contribute to the project, see Support reporting issues from iOS browsers and Chrome for Android.

In Browser{#in-browser}

For now, only Firefox Nightly and Firefox Developer Edition have a feature for reporting issues directly from the browser interface.

On Firefox Desktop, there is a ••• menu with a Report Site Issue option in the URL bar. Once selected, it automatically brings you to the webcompat reporting form with pre-filed data about your configuration.

@@insert here report-dsk-dot-menu.png@@

On Firefox Android, you can use the menu button and scroll down to the Report Site Issue option.

@@insert here android menu reporting@@

Other browser vendors are welcome to provide a way to automatically report issues to webcompat.com in a similar fashion in their nightly versions. Open an issue on the webcompat.com project.

Is It Really A Web Compatibility Issue?{#recommendations}

In general there are three type of issues:

  • A website issue. webcompat.com is the right place! Not all site issues are a webcompat.com issue. Network issues, ads and script blockers, flash requirements for every browser are part of those non-compatibility issues.
  • An issue about deceptive Web site (scams, malware). You can report them to the Report Phishing Page
  • An issue with the way the UI of the browser (not the content of the website) is working. Think about Content Reader options for example. You need to go directly to the browser bug reporting system and file an issue there @@Do we put the list of bug reporting systems? (it could be long)@@
  • An issue created by addons or web extensions. Report the issue directly to the creator of the extension.

Triage A Webcompat Issue

Someone has reported a bug. The issue is now in the needs triage list. You can help!

Triaging is an important step in the process. You will be assessing the quality of the issue. You will notice right away that a lot of issues are either invalid or lack the minimum details for being able to investigate and create a diagnosis.

Have A Neutral Test Environment{#neutral}

For having a better understanding of the issue, you will probably need to have a setup which makes it possible to have a fresh profile of the browser you are testing with. For example, on firefox you can create a profile which resets which each browser restart.

Reproducing The Issue{#reproducing}

Reproducing the issue is sometimes a very tough game. Some issues are happening because of the local settings of the person who created the report. Geographical location, preferences choices, web extensions and add-ons, OS, network constraints, logged on the services, devices and many other parameters are all possible the source of the breakage as perceived by the reporter.

Try your best to understand the report and reproduce the issue. If you have a doubt, reach out someone from the project to help. You may want to add screenshot when there are not available or when you want to share what you see yourself. Think about yourself as another bug reporter.

Possible Next Steps{#next}

If you can not reproduce the issue, check if it has been opened by an identified reporter or anonymously. If the issue has an identified reported, you may want to ask additional questions and give it one week or two before closing. Do not forget to thank the reporter for opening the issue in the first place. If the issue is anonymous, do not hesitate to close with one of the status below.

When closing, give information on the rationale for your decision. It doesn't have to be long, but that will help if we decide to reopen or for the reporters to understand the reasoning.

incomplete
The issue doesn't have enough details to be able to reproduce in a reasonable way. For example, the reporter gives a final screen which is not working, but it is impossible to infer all the steps for reaching this state.
non-compat
The issue is happening on all browsers and it is probably just bad coding from the website developers. This is out of scope of the webcompat project.
worksforme
To the best of your knowledge and your inability to reproduce, the website is working for you.
invalid
The report is totally unrelated to the work we do on the webcompat project.

If you can reproduce the issue

duplicate
A similar issue might exist on the project or there is a known bug on a browser bug tracker to duplicate against. Provide the links to the other webcompat issue or the bug tracker. Leave a comment on the bug tracker to inform that there is a duplicate. On Mozilla bugzilla, you can add the webcompat issue URL to the SeeAlso field.
needstriage
Everything has been reproduced and you hand the issue to the diagnosis crew.

Web Platform Research

Implementations Differences{#implementations}

Time to time, issues regarding Web compatibility are created by very specific implementation differences in one of the browsers. Either, an implementation bug or a vendor choice, it is worth to understand and document them.

It often requires to test in multiple browsers to understand the involved differences. Some webcompat issues are difficult to understand if we rely only on the website code. There are too many interactions. The code is fragile on a long term (websites change). Creating a reduced test case exhibiting and isolating the issue becomes then very handy to add to the browser vendor bug tracker or on the specifications issue reporting system.

We created the compat specification as a transitory space for documenting and describing the behavior of Web platform features resulting in incompatibilities. You can contribute by opening issues and documenting these differences.

Web Platform Surveys{#surveys}

Browser vendors try to implement the Web as it currently exists. The Web standards try to give a direction for what the Web should be, but, at the same time, document its state. Having a better understanding on how a Web platform feature (DOM APIs, CSS, HTTP, …) is really used by Web developers becomes key for implementors. There are certain class of issues that are interesting to understand by exploring what Web developers use for creating the site. You may want to address this kind of work by running a survey on a specific feature that could ultimately help to improve the Web platform.

@@To be reviewed by mike for its content.@@

@karlcow
Copy link
Author

karlcow commented Jan 18, 2018

report-dot-menu

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment