New Contributors to Perftest 🔥🦊⏱

This page is aimed at people who are new to Mozilla and want to contribute to Mozilla source code related to Performance Testing. Mozilla has both git and Mercurial repositories, but this guide only describes Mercurial - there are some guides for git in the Resources section.

If you run into issues or have doubts, check out the Resources section below and don’t hesitate to ask questions. :) The goal of these steps is to make sure you have the basics of your development environment working. Once you do, we can get you started with working on an actual bug, yay!

Accounts, communication

1. Set up a Bugzilla account (and, if you like, a Mozillians profile). Please include your Riot/IRC nickname in both of these accounts so we can work with you more easily. For example, Eve Smith would set the Bugzilla name to “Eve Smith (:esmith)”, where “esmith” is an example of a common Riot/IRC nickname pattern. You can also pick a fun nickname for yourself.
2. For direct communication with us it will be beneficial to setup Riot using these instructions.
3. Join our #perftest channel, and introduce yourself to the team. Check this page for who you can ping for help or to chat. We’re nice, I promise, but we might not answer right away due to different time zones, time off, etc. So please be patient.
4. When you want to ask a question on Riot, just go ahead and ask it even if no one appears to be around/responding. Provide lots of detail so that we have a better chance of helping you. If you don’t get an answer right away, check again in a few hours – someone may have answered you in the meantime.
5. If you’re having trouble reaching us over Riot, you are welcome to send an email to us instead. It’s a good idea to include your Riot nick in your email message.

Getting the code, running tests

Performance Testing

The first thing to do is to get your build environment set up. Follow the Getting Started instructions here. You can find more instructions here as well. We suggest using an artifact build when you’re asked since speeds everything up a lot. After you have the build ready and ran `./mach run` successfully you should be good to go. If you hit any issues getting ready, we can help you in #perftest.

So you’ve run Firefox locally - now what? It’s time to test it!

We do performance testing so you will be most interested in Raptor-webext, and Raptor-browsertime. You can find more information about all of the projects we have here. A simple test to start with would be this one which runs a google page load test with Raptor-webext:

   ./mach raptor --test raptor-tp6-google-firefox

To run Raptor-browsertime on the same page you only need to add the --browsertime argument. But first you have to install browsertime locally by running:

   ./mach browsertime --setup

If everything installed correctly you can now run the following:

   ./mach raptor --test raptor-tp6-google-firefox --browsertime

Note that Raptor-browsertime is under heavy development at the moment so it’s likely that you’ll hit issues there, but you can file bugs for those or let us know about them so we (or you) can fix them.

The code for these tools resides in this folder. Browsertime code can also be found here after it’s installed.

PerfDocs

Even though are primary focus is on performance testing harnesses, like Raptor, we have many other projects to work on too! If you come across bugs that talk about PerfDocs, then read on for more information on how to hack on it - it's a bit simpler.

This project is for building up documentation about all of our tests dynamically, and you can find it in the Firefox Source Tree Docs. It has two stages, a verification stage, and a generation stage. The verification stage ensures that all tests are documented and that all documented tests exist. The generation stage, as you may have guessed, generates the documentation! The first stage can be run with:

   ./mach lint -l perfdocs

This should pass because we can't land patches unless perfdocs is passing. The generation stage is run by calling:

   ./mach lint -l perfdocs --fix

If no errors are found during the verification (which is always run before generation), then the documentation information is produced. The actual document that was linked above in the source tree docs is produced in continuous integration (you can also do it locally with ./mach doc if you're interested.

The whole system is relatively simple, and you can find the code for it in this folder.

Work on bugs and get code review

Once you are familiar with the code of the test harnesses, and the tests you might want to start with your first contribution. You can follow these instructions on how to submit a patch. You can find review instructions that are specific to the team here.

How you test a patch will change depending on what's being modified. Generally, you will be running Raptor-webext (with commands similar to those listed above) or it's unit-tests to test your changes, but you can ask us in #perftest if you're not sure what you should run or if you need help getting a test command working. For the patch reviewer, you can use #perftest and someone from the team will review it (or you can put whoever helped you with the patch).

You can find “good-first-bugs” by looking in codetribute in the Test Automation section, projects from our team include Talos, Raptor, and Performance. Many team members also work on Dashboards and Reporting so that would be another good place to look. If you’re not sure what you want to hack on, ask us in #perftest - we’d be happy to help find you something. :)

Resources

These resources might not be directly related to Performance Testing or the code we work on, but they may have useful information for you to make use of.

1. You can find some more information on the team in this onboarding page.
2. Search Mozilla’s code repositories with searchfox or DXR.
3. Another guide for new contributors. It has not been updated in a long time but it’s a good general resource if you ever get stuck on something. The most relevant sections to you are about Bugzilla, Mercurial, Python and the Development Process.
4. Mercurial for Mozillians
5. More general resources are available in this little guide :maja_zf wrote in 2015 to help a student get started with open source contributions.
6. Textbook about general open source practices: Practical Open Source Software Exploration
7. If you’d rather use git instead of hg, see git workflow for Gecko development and/or this blog post by :ato.
8. A mercurial firefox cheat-sheet with helpful commands that are used often.

Acknowledgements

Much of this new contributor guide was based on the Marionette guide and uses a good amount of information from there.