How Can I Help with Orca?

There are many ways you can help contribute to Orca, and you do not have to be a technical genius. Here are a few things you can do:

1. Technical

  • If you want to help develop Orca, we can help you get started. Growing our virtual community of developers is always a goal, so welcome aboard! Knowing how to program and knowing Python and Linux will give you a huge leg up. For a general view of the accessibility infrastructure, you can read: Writing simple Python applications that sniff accessibility traffic. Here's a trivial 5 line app that just listens for object:state-changed:showing events from the AT-SPI:
    import pyatspi
    def blah(event):
          print event
    
    pyatspi.Registry.registerEventListener(blah,"object:state-changed: showing")
    
    pyatspi.Registry.start()
    Once you are familiar with the kinds of things applications give you via the AT-SPI, start digging into Orca. The Orca internals docs at the following URL are a little dated, but give you the general idea: Note that we created a lot of Orca with minimal resources. My motto was "let the user experience drive the architecture, not the other way around." As a result, I veered away from the school of astronautical architecture (i.e., paralysis by analysis) and stayed closer to the school of practicality. In addition, when faced with some toolkit implementations that were perhaps a bit buggy or provided their own unique interpretation of the AT-SPI specification, we had to make things work regardless of the bad taste those toolkits left in our mouths (and unfortunately the code).

    From there, dig into default.py and have a look around -- it is the big mainspring of the Orca clock. Turn debug on and take a look at the debug log. Note that we also try to use copious documentation in the code to help us remember why we did what we did (versus just telling you what the code is doing); eschew obfuscation. :-) Note that working on Orca also can mean working on *everything*. You may need to become expert in someone else's code outside Orca in order to debug problems since bugs often lie in the applications and toolkits. So, you need to keep a sense of humor and steer clear of that sense of despair to the best of your abilities.

  • If you feel comfortable applying patches, please test the latest patch for any Orca bug marked with "testing required" in the summary and add a comment to that bug with your findings, see below for further info.

  • Knock off one or more of the blocking bugs in external apps and toolkits. Even if you are not technical, you might consider adding your input on the bug for the blocked component. Letting people know the importance and impact of these issues can go a long way to getting them to focus on them.

  • Work on one or more of the enhancement requests.

  • Work on any of the bugs and enhancements.

  • Write a script for your favorite application. Submit it to us via Bugzilla, and give yourself credit on the Contributed Scripts page.

  • Help provide translations for eSpeak and contribute them back to the author. Read more here.

2. Help Triage Problems

Pick your favorite app (e.g. Firefox, OpenOffice, whatever). Set up an environment in which the only variable is that app, and where you can have multiple versions of that app co-existing simultaneously. Then use the most bleeding-edge version of that app as often as you can.

When something breaks, do the following:

  1. Identify as precisely as possible the version/build where things broke. The closer you can get to an exact date and/or build the better.
  2. Having found the first version/build that is broken (say, Firefox 3.6 from 15 September), reproduce the problem while capturing a full debug.out. (See the Debugging page for more info.)

  3. Perform the very same steps, commands etc. in the last version/build that is not broken (e.g. Firefox 3.6 from 14 September), also capturing a full debug.out.
  4. Compare the two debug.outs. They should be awfully similar because the only thing that's different is your favorite app, and you've taken the time to find the exact version of that app where things changed. So find out what happened: Look for events that are missing. Look for new events. Etc. A sample dissection of debug.out information can be found in the Orca-list archives: Part 1 and Part 2.

  5. Take all of the above data along with your analysis of it and file a bug against the appropriate component. That might be Orca; it might be the app you were testing.
  6. As you develop strategies for quickly pinpointing a problem, add it to the wiki so other community members can join in this effort.

We spend far more time doing the above than we do fixing the problem -- or reporting the problem to the developers who need to fix it when the bug is not within Orca. If you can identify the precise point when something broke *and* identify what exactly changed (e.g. the new/different at-spi event), it would help the Orca team out tremendously.

Beyond helping the team out, once you've stared at enough debug.out files a lot will become clear. It does take a while. You'll start to get it, because you'll see what Orca is reacting to and how it's reacting to it. From there, you can start modifying the code where Orca's doing that reacting and see what changes as a direct result of your modification. This process will expose you to Python and the general coding style and conventions used within Orca. Once you've got that down, you'll be able to start fixing bugs and ultimately writing scripts

3. Testing Patches

A patch file is a set of modifications to source code, in the following, we are assuming that the patch was made against orca master.

Visit the bugzilla page for the bug in question, and download the latest patch. Usually if you simply click on the attachment id, it will open up and you can read the modifications in the web-browser. You can copy the address, and wget it from the command line, or if you place the following bash function in your .bashrc, it will automatically download the patch for you.

function getOrcaPatch() {
patchdir=~/builds/orca/patches/
mkdir -p "${patchdir}"
patchURL="http://bugzilla-attachments.gnome.org/attachment.cgi?id=${1}"
outfile=${1}.patch
wget -q -O "${patchdir}${outfile}" "${patchURL}"
}

Then simply typing getOrcaPatch 120249 would download that patch. Then navigate to your orca source directory, and type: patch -p1 < ~/builds/orca/patches/120249.patch and the patch will be applied. Then do ./autogen.sh; make; sudo make install and restart orca, and have a good play with the new patch. Once you wish to remove the patch, again, navigate to the orca source directory, and type patch -R -p1 <~/builds/orca/patches/120249.patch Notice the only diffrence is the minus capital r switch for reversing a patch.

3.1. Testing patches with Git

Now we have moved its source code repositories from Subversion to Git and we can apply the patches (also) with Git. But first we should get the last changes before to apply the changes so we are sure the patch applies against the master:

git pull --rebase

One way for testing the patches with git is using the same bash function from before, getOrcaPatch for getting the patch and then using Git:

getOrcaPatch 120249
git apply ~/builds/orca/patches/120249.patch
./autogen.sh; make; sudo make install

This is mostly the same than the previous method but we don't care about with '-p' level is (-p1, -p2, -p0...).

To reverse the process and to have the sources as before the patch we use the same command but with the switch '-R', just like with the patch command:

git apply -R ~/builds/orca/patches/120249.patch

There is a tool that will let you work with Git and Bugzilla without using the web interface, it's called git-bz. The basic work with this tool would be:

# Apply patches from the given bug
git bz apply bugzillla.gnome.org:1234

# Attach the last commit
git bz attach bugzilla.gnome.org:1234 HEAD

# Attach everything starting at an old commit
git bz attach bugzilla.gnome.org:1234 b50ea9bd^..

You can see the help for this tool and more examples here.

Good luck, and thanks for getting involved.

4. Not-so-technical

  • Don't be afraid to submit bugs. This will get our immediate attention and help us improve Orca.

  • Write up instructions for installing/configuring Orca/speech/braille on your favorite operating system distribution. Include a pointer to it in the "Installing and Setting up Orca" section on this page.
  • Write up instructions on how to use your favorite application. Add it to the Accessible Applications page on this WIKI.

  • Join the GNOME Translation Project and help translate Orca to your favorite language.

  • Conduct a user study and send us your results. Here's a recent report done by Ellen Reitmayr. It was very useful to us!

There's no shortage of work to do, and we love the community. We strongly encourage you to join the Orca mailing list (Archives) and participate in the discussion there. It's not just for technical people.


The information on this page and the other Orca-related pages on this site are distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Projects/Orca/HowCanIHelp (last edited 2015-11-19 00:51:54 by AndersJonsson)