From MozillaWiki
Jump to: navigation, search

Working on Web Compatibility Issues

As said on Web Compatibility page:

A person should be able to use the Web from which ever device and browser they are using.

There are many ways we, Web users, can help make the Web a better place:

  • Collect information about well-known sites in your own country.
  • Report the issues in a useful way.
  • Analyze the Web sites so that the bugs contain useful information.
  • Contact Web sites owners (or developers) for fixing Web compatibility issues.

The work and the effort of the community is key to the success of the open Web. These efforts have to be considered in the constraints of the business requirements of each contacted Web site. We are not here to blame, we are here to make the Web open to anyone. The Web compatibility effort is driven by two projects mobile Web compatibility and desktop Web compatibility.

Reporting a Web compatibility issue


  1. You visit a webpage.
  2. Something about the experience is broken: layout is messed up, video doesn't play, buttons don't work, etc.
  3. Check in another browser. Is it working there but not in Firefox?

You can help!

Note: We try to avoid working on fixing Web sites which are working badly everywhere. We focus first our energy on Web sites which are broken in one browser and not others. Issues caused by add-ons or ad blockers are also not considered web compatibility issues.


You will need a GitHub account. If you don't have one, you can create a new account (it's free). You can also file bugs anonymously, but that makes it hard to follow up— filing with an account is preferred!

Steps to follow

A good bug report includes steps to reproduce an issue, and what the expected outcome was. The more details you give, the better chance the issue will be properly addressed. If, for example, one must log in to see the issue, it is important to say so. Screenshots can also be very helpful!

  1. Create a new bug on (if you have the webcompat reporter add-on installed, just click on the icon to open this for you with some of the info pre-filled).
    1. Include the URL
    2. Include the steps to perform to see the problem after opening that URL
    3. Describe the expected behavior
    4. Describe the actual behavior
    5. Give relevant information about your device and your browser
  2. (Bonus) Test in one or more browsers to understand the differences

Someone might ask further questions in the bug report to better understand the issue. This is why it's important to report issues with a GitHub account — you'll be able to get notifications about questions and progress.

Do not forget: Be nice. It is our collective effort.

Diagnose a Web Compatibility Issue

Analysis is broken down into two processes: triage and diagnosis. The triage process involves testing the reported issue to validate if the issue:

  • Can be reproduced
  • Is considered a valid Web Compatibility bug
  • Has been reported previously (a duplicate)

There are many ways of diagnosing a web site for Web Compatibility issues. We could write an entire book with the types of issues and techniques used to find them.

Diagnosis Process and Tools

The work is based on a diagnosis process. You may want to read this. It gives useful hints on how to organize the work. some tools and techniques for investigating bugs have also been described.

Finding The Right Contact on a Web site

For solving the issues, we often need to find the right person on the Web site. It is often the hardest part of the job, but it's where you can really make a difference. Some Web sites are written in a language that you are mastering. Some Web sites are in country where we do not have much context on how to contact the right person. You can help. The open Web is the work of everyone. Here is a concrete example. If you have more tips, share them here.

There is more than one strategy for finding a person related to a Web compatibility issue. Here are a few:

  • Does the company have a developer relations department?
  • Is there a support email address or Web form on the Web site?
  • Is there an email address for the Communications department?
  • Is there an email address for the Technical department?
  • If the company has an organigram of their management, search for people who are CTO, Marketing, or Communications related, then check online if you can find them either on Twitter or Linkedin. But, be careful. If the person is obviously only using the account for personal stuff, do not bother them.
  • Does the company have a Twitter account?
  • Does the company have a Github, Bitbucket or Google code account?
  • As a last resort, you may try through their Press relations address which is usually open.
  • Call a phone number of the company, though you may be bounced around.
  • You might want to check the WHOIS record for the domain name. In some rare cases, it is possible to find useful information about the owner of the site.

Before contacting, read the next section.

Negotiating with the Web site for fixing a Web compatibility issue

First of all, this is a negotiation process. People you will try to contact have their own set of constraints and that might be difficult for them to understand, fix the issue. So be nice.

  • Never ever be aggressive with the persons you are trying to reach out. We want a better Web, not an angry Web ;).
  • Never assume you are contacting the right person.
  • Do not harass people with a lot of emails (even if they are nice to you). A good rule of thumb is to wait one week between contacts. Then a month for the third contact. If nothing has happened during the 5 weeks, give up.
  • Never share publicly the emails or names of people in the bug report if they have not decided to reveal themselves. Sometimes people will be willing to help fix a Web site without necessarily telling their management. Exposing them would make their work more difficult.
  • Invite people to participate to the bugzilla themselves.
  • If someone doesn't want to open a bugzilla account but is willing to share his/her comments in the bug report, help them to publish it (but only if they agree).

There is no perfect email for contacting Web site, but if you think you are not necessarilyy contacting the right person it helps to write shorter emails. We created some templates in different languages. They are very simple, straight to the point and asking for better contact information. It is just an example. Some countries require more formalism, etc. Adjust depending on the local culture in your own language.

On twitter, it could be straightforward. For example

   @example Hi, would you know who I should contact 
   for Web site issues? 

Bugzilla Conventions for Web Compatibility Issues

We are using a list of conventions in the Web Compatibility activity.

Mobile Web Compatibility Issues By Countries

Web Compatibility often requires to communicate with the Web site developer or owner in his/her own language. We try to keep a list of countries for people with specific language skills can get easily involved in the work.

Collecting Information And Surveys

Once a mobile device has been introduced in a new country, some Web sites will exhibit issues of Web compatibility. Every country has popular Web sites which are related to their local market (for example well known press and magazines sites).

Steps to follow

  1. Create a page with a list of top Web sites. See for example Brazil, India or Germany
  2. Start small, grow it little by little
  3. For each Web site, test the site with Firefox Android (and Opera Mobile, IEMobile, Chrome Mobile, Android, etc.). You can get help by having a pre-generation of screenshots for your Web site list.
  4. Note differences and open individual bugs for each individual issue (see below)