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

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

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)