Compatibility/Guide

This is a draft guide. It documents certain things but it will change time to time and will be used to feed documentation on MDN.

---

As said on Web Compatibility page:

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

This guide is an early draft started on July 2013. It might be split in smaller individual pages to make it easy for anyone to participate.

The goal is to give the tools and guidance for helping the Web community to:

• Help report the issues in a useful way
• Analyze the Web sites so that the bugs contain useful information
• Give guidance on how to contact Web sites owners, developers for fixing Web compatibility issues.

We can't solve everything ourselves. 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 sites. We are not here to blame, we are to make the Web more open to anyone. The Web compatibility effort is driven by two projects mobile Web compatibility and desktop Web compatibility.

You can help the open Web by:

• reporting an issue
• analyzing the issue
• helping us find the right person to contact
• negotiating with the Web site to get it fixed

Reporting a Web compatibility issue

What?

You reached a Web site and you have not been able to use it with your Web browsers of choice. You have checked with a couple of other browsers and you noticed a difference. You can help.

This guide is focused on Mozilla browsers but you can also help other browser vendors. If you have an issue with Opera (Bug Wizard), Chrome (Bug), Safari (Bug) or Internet Explorer (Bug)

Requirements

You will need a Mozilla bugzilla account. If not create a new account.

Steps to follow

The person (volunteer or Mozilla engineer) will need to know which steps you have followed to reach the issue. The more details you give, the better chance to get the issue being properly addressed. If, for example, one must log in to see the issue, it is important to say so.

1. Create a new bug in Bugzilla
   1. Describe the steps you have been doing for reaching the point where you have an issue: Example of steps
   2. Describe what is happening
   3. Describe what you were expecting
   4. Give information about your device and your browser
2. (Bonus) Test in one or more browsers to understand the differences: Example of tests in different browsers

Someone might ask further questions in the bug report to better understand the issue.

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

Analyzing for Web Compatibility Issues

There are many ways of analyzing a Web site for Web Compatibility issues. We could write an entire book with the type of issues and techniques to find them out.

Mozilla Bugzilla Process for Analysis

You might want help analyzing Mobile Web Compatibility bugs. A bug which has the status NEW or ASSIGNED are basically the same.

1. When analyzing the bug, take it (assign yourself).
2. Once you discovered the type of issue affecting the site
   1. document in a comment
   2. flag it with a whiteboard keyword for example [serversniff] if it's related to server side user agent detection.
3. If you do not plan to work further on the bug, such as contacting the Web site, Unassign yourself

Server Side User Agent Detection

User Agent String detection on the server side leads to different strategies by the site owner. They are used for delivering content to specific browsers and/or specific devices.

The negotiation is done at the HTTP level.

• Redirection to a subsection of their domain. Ex: http://example.com/ to http://example.com/m
• Redirection to a another domain. Ex: http://example.com/ to http://m.example.com/
• Delivering different types of content on the same domain name.

We can explore what are the influence of an HTTP HEAD or GET and analyzes the answers. Often there will be redirects as indicated by the status code 301, 302, 307 or 308, with a Location: HTTP header Location: http://m.example.com/. (Be careful, some sites send location all in lowercase, in case you are grepping through HTTP headers)

Once we have identified that it is really done server-side, we can add the whiteboard flag [serversidesniff]. An example of an analysis of server side detection.

HTTP Introspection Tools

curl and httpie are two extremely useful tools for analyzing what is happening at the HTTP level.

Firefox

• Firefox Network Monitor (built-in from version 23)
• Firebug Add-on

Others

• curl (CLI)
• httpie (CLI)
• Opera Dragonfly (Presto)

Client Side User Agent Detection

[lib-yui] [clientsniff]

Things to think about when testing

• Clearing cookies and storage information. Some Web sites, once it has been accessed the first time, will add a cookie for keeping your preferences. Some of these cookies might be for the type of site such as mobile or desktop. It is better to clear the cookies and storage information, if you need to test the site as a first user.
• Remove UA override already installed. Currently Firefox OS devices have a UA override mechanism. It helps users to get a mobile version even if the site is not doing the identification properly. The unfortunate consequence is that it becomes harder for testing. So it is necessary to remove the UA override from the device. 1.0 and 1.1 have an in-device list that you can edit with mozua.sh. In 1.2, the list will be dynamic on the server side.

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 the hardest part of the work, 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 has a developer relations department?
• Is there a support email address or Web form on the Web site?
• Is there an email address for Communications department?
• Is there an email address for Technical department?
• If the company has an organigram of their management, search for people who are CTO, Marketing, Communications related, then check online if you can find either on twitter or linkedin. Be careful. If the person is obviously using the account for only 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 the Press relations address which is usually open.
• Call a phone number of the company, you might 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, except if you really know you do.
• Do not harass people with a lot of emails (even if they are nice with you). A good rule of thumb is to wait one week in between two contacts. Then a month for the third contact. If nothing has happened during the 5 weeks, give up.
• Never share publicly the emails, names of people in the bug report if they have not decided to reveal themselves. Sometimes people will be willing to help fixing a Web site without necessary 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 agreed)

There is no perfect email for contacting Web site, but if you think that you are not necessary contacting the right person it helps a lot writing a shorter email. We created some templates in different languages. There are very simple, straight to the point and asking for a 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? 
   See https://bugzilla.mozilla.org/show_bug.cgi?id=<issue_number>

Bugzilla Conventions for Web Compatibility Issues

Status

This is a short explanation of the bug status in Web Compatibility Area.

• UNCONFIRMED: This bug has been opened, probably through Mobile Web Compat form
• NEW: The bug has been confirmed and probably analyzed. Whiteboard flags are added. It's free for everyone to work on it.
• ASSIGN: A person has been assigned on the bug. It has been taken.
• FIXED: A site was fixed in response to a request made by volunteers through Mozilla.
• WORKSFORME: If the problem is no longer there but we haven't asked for any fixes (yet)
• INVALID: If a bug is not a valid Tech Evangelism bug in the first place

whiteboard keywords for categorizing the issues

We are using a set of keywords in the whiteboard field to help us figuring out priorities, languages, etc.

• [contactready]: Once the Web site has been analyzed for Web compatibility issues. Someone can take the bug and contact the Web site for achieving a resolution. List of Web sites to contact
• [sitewait]: Once the Web site has been contacted for Web compatibility issues. This helps to not have two separate persons contacting the same Web site. Leave also a comment with the date when you contacted the site. list of contacted Web sites
• [country-ISOCODE]: Some websites are dedicated to a specific country. For example, a French Web site can be classified as [country-fr], a japanese Web site as [country-jp], for international Web sites you can use [country-all]
• [uaoverride]: When the current bug is about the UA override list added on to Firefox for Android or Firefox OS
• [clientsniff]: When the sniffing is happening on the client-side such as HTML or JS
• [serversniff]: When the sniffing is happening on the server-side such as HTTP redirection and/or different content being served on the same domain
• [lib-foo]: When related to a specific JS lib being used. Example [lib-yui] [lib-jquery] [lib-mootools]
• [tier1]: When the issue is about a site not giving the nicest experience that some other browsers get. For example, getting the low-end mobile version instead of the shiny touch version.

Dependencies bugs

• bug 739832 for dependencies on Webkit CSS prefixes for Firefox Android.

Mobile Web Compatibility Issues By Countries

• Brazil
• Colombia
• Greece
• India
• Poland
• Spain
• Venezuela