Yura Zenevich

Resources For Contributing to Firefox OS Accessibility.

2014-11-28T00:00:00+00:00

Resources For Contributing to Firefox OS Accessibility.

28 Nov 2014 - Toronto, ON

I believe when contributing to Firefox OS and Gaia, just like with most open source projects, a lot of attention should be given to reducing the barrier for entry for new contributors. It is even more vital for Gaia since it is an extremely fast moving project and the number of things to keep track of is overwhelming. In an attempt to make it easier to start contributing to Firefox OS Accessibility I compiled the following list of resources, that I will try keeping up to date. It should be helpful for a successful entry into the project:

Firstly, links to high level documentation:

Git

Gaia project is hosted on Github and the version control that is used is Git. Here's a link to the project source code:

https://github.com/mozilla-b2g/gaia/

One of my coworkers (James Burke) proposed the following workflow that you might find useful (link to source):

Fork Gaia using Github UI (I will use my Github user name - yzen as an example)
From your fork of Gaia (https://github.com/yzen/gaia), clone that locally, and set up a "remote" that is called "upstream" that points to the mozilla-b2g/gaia repo:

    git clone --recursive git@github.com:yzen/gaia.git gaia-yzen
    cd gaia-yzen
    git remote add upstream git@github.com:mozilla-b2g/gaia.git

For each bug you are working on, create a branch to work on it. This branch will be used for the pull request when you are ready. So taking this bug number 123 as an example, and assuming you are starting in your clone's master branch in the project directory:

    # this updates your local master to match mozilla-b2g's latest master
    # you should always do this to give better odds your change will work
    # with the latest master state for when the pull request is merged
    git pull upstream master

    # this updates your fork on github's master to match
    git push origin master

    # Create bug-specific branch based on current state of master
    git checkout -b bug-123

Now you will be in the bug-123 branch locally, and its contents will look the same as the master branch. The idea with bug-specific branches is that you keep your master branch pristine and only matching what is in the official mozilla-b2g branch. No other local changes. This can be useful for comparisons or rebasing.
Do the changes in relation to the bug you are working on.
Commit the change to the branch and then push the branch to your fork. For the commit message, you can just copy in the title of the bug:

    git commit -am "Bug 123 - this is the summary of changes."
    git push origin bug-123

Now you can go to https://github.com/yzen/gaia and do the pull request.
In the course of the review, if you need to do other commits to the branch for review feedback, once it is all reviewed, you can flatten all the commits into one commit, then force push the change to your branch. I normally use rebase -i for this. So, in the gaia-yzen directory, while you are in the bug-123, you can run:

    git rebase -i upstream/master

At this point, git gives you a way to edit all the commits. I normally 'pick' the first one, then choose 's' for squash for the rest, so the rest of the commits are squashed to the first picked commit.

Once that is done and git is happy, you can the force push the new state of the branch back to GitHub:

    git push -f origin bug-123

More resources at:

Source Code

All apps are located in apps/ directory. Each up is located within its own directory. So for example if you are working on a Calendar app you would be making your changes in the apps/calendar directory.
The way we want to make sure that the improvements that we work on actually help Firefox OS accessibility and do not regress we have a policy of adding gaia-ui python Marionette tests for all new accessible functionality. You can find tests in the tests/python/gaia-ui-tests/gaiatest/tests/accessibility/ directory.

More resources at:

Understanding the Gaia codebase

Building and Running Gaia

Testing

Testing Gaia code changes
Gaia unit tests used for low level unit testing.
Gaia integration tests used for higher level integration tests.
Gaia UI tests used for higher level integration tests. All accessibility tests are written as Gaia UI tests.

Localization

Localization is very relevant to accessibility especially because one of the tasks that we perform when making something accessible is ensuring that all elements in the applications are labeled for the user of assistive technologies. Please see Localization best practices for guidelines on how to add new text to applications.

Debugging

Using a screen reader

Using a device or navigating a web application is different with the screen reader. Screen reader introduces a concept of virtual cursor (or focus) that represents screen reader's current position inside the app or web page. For mode information and example videos please see: Screen Reader

Accessibility

Here are some of the basic resources to help you get to know what mobile accessibility (and accessibility) is:

yzen

TIL Debugging Gaia with B2G Desktop and WebIDE.

2014-10-24T00:00:00+00:00

TIL Debugging Gaia with B2G Desktop and WebIDE.

24 Oct 2014 - Toronto, ON

With some great help from Rob Wood from Mozilla Firefox OS Automation team, I finally managed to get Gaia up and running and ready for debugging with B2G Desktop Nightly build and WebIDE.

It is currently impossible to develop / debug Gaia using Firefox for Desktop. Thus, it's a pretty big barrier for new contributors who are just starting out with Gaia. Turns out, it is fairly easy to run Gaia codebase with B2G Desktop build. Here are the instructions:

Prerequisits:

Download and install B2G Desktop Nightly build
Download and install Firefox for Desktop Nightly build
Check out Gaia code base: git clone https://github.com/mozilla-b2g/gaia.git

Instructions:

In your Gaia repository build a Gaia user profile from scratch: make
Run the following command to start the B2G Nightly build with Gaia profile that you just built: /path/to/your/B2G/b2g-bin -profile /path/to/your/gaia/profile -start-debugger-server [PORT_NUMBER] For example: /Applications/B2G.app/Contents/MacOS/b2g-bin -profile /Users/me/gaia/profile -start-debugger-server 7000
Start Firefox for Desktop Nightly build
Open WebIDE (Tools -> Web Developer -> WebIDE)
Press Select Runtime -> Remote Runtime
Replace the port with the one used in step 2 (7000) and click OK
A dialog should pop up within the B2G emulator asking to permit remote debugging. Press OK
At this point you should have access to all apps bundled with the profile as well as the Main Process via WebIDE
When you make changes to Gaia code base, you can run make again to rebuild your profile. Hint: if you are working on a single app, just run APP=my_app make to only rebuild the app.

yzen

isfirefoxosaccessibleyet.com

2014-09-24T00:00:00+00:00

isfirefoxosaccessibleyet.com

24 Sep 2014 - Toronto, ON

Eitan from Mozilla's accessibility team was nice enough to reserve a isfirefoxosaccessibleyet.com domain where we could track Firefox OS accessibility status easily and in the open. I am really happy to announce that isfirefoxosaccessibleyet.com is now ready to be seen in public.

There are several bits of information about each app (including the overall system) that you can find there: an overall accessibility score, a number of opened, resolved and currently in progress bugs. We also provide links to the actual bug lists handy in case you need to dig deeper.

For anyone who wants to help out:

If you are a user and want to file a bug, you should be able to find a link inside each app's section.
If you are a developer and want to hack on Gaia accessibility, each app section has an up-to-date lists if high priority and good first bugs.

Please feel free to check it out!

yzen

Building and Flashing a Firefox OS device

2014-05-07T00:00:00+00:00

Building and Flashing a Firefox OS device

07 May 2014 - Toronto, ON

Yesterday I found a mystery box sitting on my table. I was super excited to discover that I finally got the new "Flame" reference Firefox OS device (MDN). So let the testing begin!

First of all, I wanted to comment on the great build and hardware quality that the device has! I was impressed to a point of wanting to dog-food the device as my primary smartphone. Unfortunately, none of the Firefox OS devices released to date work on Wind Mobile network (1700/2100 AWS band).

My second thought was to flash it with the latest Firefox OS build. Since I am using OSX as my primary working environment, I opted for using the current Ubuntu LTS with Virtual Box and Vagrant. I was using that setup for a while now with the Inari device without any issues. The first thing I discovered when building for "Flame" is that my build now explicitly fails because of the non-case sensitive file system (I shared the source for B2G, gecko and Gaia between the host and the guest environments).

Given that other developers that work on OSX and develop for "Flame" might face the same issues, here is a step by step guide to setting up, building and flashing the reference device:

Case sensitive disk image

NOTE: proceed to the next step if you have a case-sensitive file system already

To create mountable case-sensitive disk image run

  hdiutil create -volname 'firefoxos' -type SPARSE -fs \
  'Case-sensitive Journaled HFS+' -size 40g ~/firefoxos.sparseimage
  open ~/firefoxos.sparseimage

The drive will now be located at /Volumes/firefoxos/

Source code

The disk image is the place to keep the B2G source code. In case you have a pre-existing Gaia and gecko repositories you can use symlinks to/for them.

Now is also a good time to set an environment variable that will be used to reference the path to B2G source: export B2G_PATH="/Volumes/firefoxos/B2G"

Build environment

By now you should have Virtual Box and Vagrant installed. Vagrant makes it really easy to create and configure the build environment with just one command. All of the provisioning stuff is specified in this Vagrantfile that you should save somewhere close to where you keep your other VMs.

Now navigate to the directory you saved the Vagrantfile to. And run the following command:

vagrant up

It will take some time to set everything up but once you are done your VM should be easily accessible via ssh, so type:

vagrant ssh

and you are in.

Configure, build and flash

At this point you are all set up and ready to roll. Here's what you need to do:

Connect your device via USB and verify that it is visible to the VM: adb devices should list it.

  cd B2G // host's B2G_PATH is synced to guest's $HOME/B2G
  ./config.sh flame // Will take some time to fetch everything
  ./build.sh // Will take a very long time to build everything
  ./flash.sh // Will flash the device with your new shiny build

Hopefully everything worked for you and you are ready to hack on B2G or Gaia from OSX. The changes you make will be synced to the VM. When you are ready to build again, just ssh to it and run the necessary commands (more here).

yzen

FirefoxOS Accessible Tabs

2014-05-01T00:00:00+00:00

FirefoxOS Accessible Tabs

01 May 2014 - Toronto, ON

Firefox OS accessibility has been one of the main focus items for our team for quite a while now. The TODO list is fairly long so it's important to prioritize the most impactful items. We recently completed making the Tabs widgets accessible across all Firefox OS applications.

Tabs is part of Building Blocks - a collection of commonly used patterns in CSS, HTML and, eventually, Javascript that comprise different commonly used widgets such as header, list, button, etc (currently located here in Gaia source code). This meant that by addressing Tabs accessibility we would improve accessibility of all Gaia apps that use them. It would also serve as a good accessible Tabs template for the upcoming apps that would need to use them.

Most of the changes were specific to HTML and CSS with a little extra Javascript work, all described below:

Tabs in Gaia now use the following markup:

<ul role="tablist" class="bb-tablist">
  <li role="presentation">
    <a id="tab1" href="#tabpanel1" role="tab" aria-controls="tabpanel1"
      aria-selected="false">Tab 1</a>
    <div id="tabpanel1" class="bb-tabpanel" role="tabpanel"
      aria-labelledby="tab1">Tab Panel 1</div>
  </li>
  ...
  <li role="presentation">
    <a id="tab2" href="#tabpanel1" role="tab" aria-controls="tabpanel2"
      aria-selected="true">Tab 2</a>
    <div id="tabpanel2" class="bb-tabpanel" role="tabpanel"
      aria-labelledby="tab2">Tab Panel 2</div>
  </li>
</ul>
// Note: elements with the role="tabpanel" do not have to be siblings of the
// role="tab" elements.

You can find the CSS, that Tabs in Gaia use, here. As you can see from the markup above and the corresponding CSS file, there is an explicit separation between the aria roles and the styling. This was done to address a common pitfall of using the aria roles as CSS selectors to obtain the necessary styling on elements with different semantics.
The only Javascript bit that was required was related to handling aria-selected attribute between the list of tabs (accessibility_helper.js). AccessibilityHelper.setAriaSelected would need to be called from the app code that is responsible for handling navigation between tabs.

As of right now, if an app implementation requires a Tabs widget, developers need to use the above markup, include the above CSS file as well as the accessibility_helper.js file. And if they do, their users should be able to enjoy fully screen reader accessible Tabs.

yzen

Mobile Accessibility Checklist

2014-04-30T00:00:00+00:00

Mobile Accessibility Checklist

30 Apr 2014 - Toronto, ON

This is a concise checklist of accessibility requirements for mobile developers. It is intended to continuously evolve as more patterns arise.

Colour

Colour contrast MUST comply with WCAG 2.0 AA Level requirement
- Contrast ratio of 4.5:1 for normal text (less than 18 point or 14 point bold)
- Contrast ratio of 3:1 for large text (at least 18 point or 14 point bold)
- Colour Checker
Information conveyed via colour MUST be also available by other means (underlined text for links, etc)

Visibility

Hiding techniques such as zero opacity, z-index order and off-screen placement MUST NOT be used exclusively to handle visibility
Everything other than the current visible screen MUST be truly invisible (especially relevant for single page apps with multiple cards)
- USE hidden attribute or visibility or display style properties
- Unless absolutely unavoidable, aria-hidden attribute SHOULD NOT be necessary

Focus

All activatable elements MUST be focusable
- Standard controls such as links, buttons, form fields are focusable by default
- Non standard controls MUST have an appropriate role attribute assigned to them: button, link, checkbox etc (ARIA Roles)
Focus should be handled in a logical order and consistent manner

Text Equivalents

Text equivalent MUST be provided for every non strictly presentational non-text element within the app
- Use alt and title where appropriate (UPDATE: See Steve Faulkner's post about Using the HTML title attribute)
- If the above attributes are not applicable use attributes such as aria-label, aria-labelledby or aria-describedby (ARIA Properties)
Images of text MUST be avoided
All form controls MUST be labeled for the screen reader user

Handling State

Standard controls such as radio buttons and checkboxes are handled by the operating system. However, for other custom controls state changes must be provided via aria states: aria-checked, aria-disabled, aria-selected, aria-expanded, aria-pressed (ARIA States)

General Guidelines

An app title MUST be provided

Headings MUST not break hierarchical structure

<h1>Top level heading</h1>
  <h2>Secondary heading</h2>
  <h2>Another secondary heading</h2>
    <h3>Low level heading</h3>

Aria landmarks SHOULD be used to describe an app or document structure: banner, complementary, contentinfo, main, navigation, search (ARIA Landmark Roles)
Touch event handlers MUST only be triggered on touchend event
Touch targets MUST be large enough for the user to interact with (BBC Mobile Accessibility Guidelines)

TIL Running Gaia tests on Try.

2014-03-27T00:00:00+00:00

TIL Running Gaia tests on Try.

27 Mar 2014 - Toronto, ON

After getting some Gaia unit test failures on Try when one of my pull requests was merged in, I discovered how to use Try to test my pull request branch myself. This is a pretty important time saver for myself and anyone else who has to deal with my mistakes. So here are the instructions:

Prerequisits:

Commit Level 1
Have your [pull request] Gaia branch handy.
Have a local mercurual repository for mozilla central.

Instructions:

You need to modify the following file in your mozilla central source b2g/config/gaia.json from:

{
    "git": {
        "git_revision": "",
        "remote": "",
        "branch": ""
    },
    "revision": "57c407d3e94ba322688b4bd121eda317806ab44e", // Current rev.
    "repo_path": "/integration/gaia-central"
}

{
    "git": {
        "git_revision": "",
        // Replace with your own gaia remote.
        "remote": "https://github.com/yzen/gaia.git",
        // Replace with the [pull request] branch you want to test.
        "branch": "969553"
    },
    "revision": "57c407d3e94ba322688b4bd121eda317806ab44e", // Current rev.
    "repo_path": "/integration/gaia-central"
}

The correct trychooser message is:

try: -b o -p linux64_gecko,linux32_gecko,macosx64_gecko -u all -t none

That's it! When you push to Try, the tests will run against your branch instead of the current /integration/gaia-central revision.

yzen

TIL Debugging Mochitests.

2014-02-24T00:00:00+00:00

TIL Debugging Mochitests.

24 Feb 2014 - Toronto, ON

Turns out there's an easy way to debug Chrome JS in mochitests, as described by Gijs Kruitbosch in his blog: Debugging Chrome JS and Mochitest Redux. All you need to do is to use the --jsdebugger flag. Your tests will start with the debugger enabled by default and stopped before their execution. You can add breakpoints on the fly or use the debugger; command in your JavaScript code.

Here's an example of running some of the a11y tests from your gecko-dev directory:

./mach mochitest-a11y --jsdebugger accessible/tests/mochitest/jsat/

yzen

FirefoxOS Screen Reader Toggle

2014-02-24T00:00:00+00:00

FirefoxOS Screen Reader Toggle

24 Feb 2014 (Updated: 7 Mar 2014) - Toronto, ON

UPDATE: After some initial user/developer trials we opted for a different hardware button combination instead of the power button press. Instead of pressing the power button three times, the user now needs to press volume up then volume down buttons three times to hear the instructions.

This post is going to be an inaugural one for my new blog where I will try to give small updates about all things accessibility for FirefoxOS, and Mozilla in general.

We are making progress every day on things like the screen reader for mobile (FirefoxOS and Firefox for Android), accessibility for the essential FirefoxOS apps and a number of other platform-wide accessibility improvements.

One of such recent improvements is a shiny new quick toggle for our screen reader. With this improvement the user can enable or disable the screen reader at any point, as long as the phone is turned on (including the first time use setup). To enable the screen reader, the user needs to press the power button three times in short succession (within the maximum of one second between the presses). The phone will then announce that the screen reader will be turned on if the user repeats the action of pressing the sleep button three more times in the same fashion. The instructions are identical for disabling the screen reader.

Sometimes getting those three presses right might feel a little bit tricky. It seems like the events from the hardware power button get fired only when the presses are really pronounced. Thus, there is more room for improvement. There is of course the actual accessibility setting in the main Settings app in case you want to play around with things like the speech rate and volume.

More updates are coming..

yzen