Revision as of 18:34, 24 July 2023

This page is aimed at people who are new to Mozilla and want to contribute to projects related to Performance Tools. 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!

Getting started

1. Set up a #Bugzilla account.
2. Set up a #Phonebook account.
3. For direct communication with us it will be beneficial to setup #Matrix, join our public channels, and introduce yourself.

Getting the code

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 [1]. A simple test to start with would be this one which runs a google page load test with Raptor:

   ./mach raptor --test google-search

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 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 test projects at Performance/Tools/Testing/Reviews.

How you test a patch will change depending on what's being modified. Generally, you will be running Raptor (with commands similar to those listed above) or it's unittests 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. :)

Meetings

• When: Weekly on Wednesdays at 15:00 UTC (08:00 PST, 11:00 EST, 18:00 EET)
• Where: Zoom ID 110-819-485
• Notes: Google Docs

Phonebook

The people directory is a secure place to quickly find your team members and easily discover new ones.

Please ensure your profile has:

• photo (of you!)
• username (this is included in your profile URL)
• #GitHub identity
• #Bugzilla identity
• #Matrix nick
• #Slack nick

Calendar

There's a Performance shared calendar (iCal), which is primarily used for PTO. Add this calendar to your google calendar by taking the iCal link and using it in the "Add Calendar -> From URL" section.

PTO

Add any PTO to the shared calendar (see above) and team meeting notes so the team are aware. During PTO please also update your name in Bugzilla's user preferences to indicate that you are away, and when you will return.

Communication

Groups

Feel free to sign up to the following groups, and post to them when you have something to share or questions to ask.

• perftest is for team communications and setting up test accounts
• performance is for general discussion and announcements
• perfteam is for the broader performance team
• perf-sheriffs is for discussions related to performance sheriffing
• perftest-alerts is for alerts related to performance tests

Matrix

Join our public channels listed below and introduce yourself. See Performance/Tools#Who_we_are 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. When you want to ask a question on Matrix, 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. If you’re having trouble reaching us over Matrix, you are welcome to send an email to us instead. It’s a good idea to include your Matrix nick in your email message.

• #perf- General performance chat
• #perftest- Public channel for testing related projects
• #profiler- Public channel for the Firefox Profiler project
• #perfteam- Public performance team channel
• #perfsheriffs- Performance sheriffs channel

Slack

Here are some useful Slack channels to start with:

• #announcements - Global communication and announcements
• #moco - Used for questions during internal meetings
• #newsroom - Firefox and relevant tech news
• #servicedesk - Internal IT support for employees
• #peopleteam - People support

Credentials

There's a shared 1Password vault for credentials that you may need to access. Please submit a request for 1Password from ServiceDesk. Once you have an account and the software set up (available on iOS, Android, Windows, macOS) you can be added to the team vault.

Hardware

List any hardware devices that you have assigned to you in this document. This can be valuable if we need to identify somebody on the team that has a specific device or platform for running tests, reproducing issues, etc. You may need additional hardware such as mobile devices, laptops, etc. You can request this equipment from The Hub.

Bugzilla

You will need to create an account in Mozilla's instance of Bugzilla. See BMO/UserGuide for how to get started. It's helpful to include your Matrix/Slack handle in your name field prefixed by : so you can quickly be identified by other users of Bugzilla. Other details that can be helpful are your preferred pronouns, current timezone, and if you're currently on PTO. For example:

 Dave Hunt [:davehunt] [he/him] ⌚BST (away until 1st January 2021)

Products/Components

The relevant components for the team are:

• Core::Gecko Profiler
• Firefox Profiler
• Testing::AWSY
• Testing::Condprofile
• Testing::mozperftest
• Testing::Performance
• Testing::Raptor
• Testing::Talos
• Tree Management::Perfherder

Whiteboard Entries

The following whiteboard entries are used by the team:

• [perftest:triage] - discussion required in triage.

Keywords

See Performance/Bugzilla#Keywords

Resources

• Bug writing guidelines
• Bugzilla etiquette

GitHub

If you don't already have one, you will need to create a GitHub account and enable two-factor authentication.

We have a GitHub team for simplifying access to repositories. All team members that belong to the Mozilla organisation should be added to this team as members. Team maintainers can add new members following the process documented here. Other contributors will need to be manually granted access to individual repositories as needed.

Shared folder

We have a shared folder in Google Drive.

Sheriffing

Performance sheriffs will need to complete the following:

• Request an LDAP account
• Request commit access:
  • Level 1: bug 1398609
  • Level 3: bug 1509284
• Request access to Treeherder sheriff group: bug 1506882
• Training (ranked)
• Join the perf-sheriffs Google Group

Review policy

When you push a commit up for review, you should use the following syntax to request review from the perftest review group:

 r=#perftest

For most patches, a single r+ from one reviewer is required to be allowed to be sent off for integration. More reviewers can pitch in on the same review, and Lando will in this case automatically rewrite the commit message to show who was involved signing off the patch, for example:

 Bug 1546611 - Fix "None" checks when validating test manifests; r=perftest,dhunt

See the section "Write Sensible Commit Messages" here for how to form good commit titles and summaries.

When you occasionally you have to single out individuals for specific topic expertise, you add an exclamation mark behind the nickname:

 r=#perftest,dhunt!

This will add the patch to the shared review queue, but also block the review from landing pending Dave's approval. Requested changes by other reviewers will also block the review.

Note that a Herald rule exists that will set this group as a blocking reviewer for certain paths in the tree. This was configured via bug 1618249.

Module ownership policy

If a patch touches code in a module owned by someone outside of the team, you must follow the module ownership policy and request review from the module owner or a peer listed in Modules.

Duties

Everyone on the team will be expected to carry out the following duties to ensure effective collaboration both within the team, and with other teams.

Code reviews

Visit active revisions in Phabricator every day to:

• Review any Must Review and Ready to Review patches. Pay particular attention to any patches that have yourself as the sole reviewer. Consider adding the #perftest review group for a wider audience of reviewers. All review requests should receive a response (not necessarily a complete review) within 1 working day.
• Follow up on any Waiting on Review patches by prompting appropriate team members for a review.
• Review any Waiting on Authors patches and prompt the authors if there is an action they need to take.

Bugzilla requests

Visit the request queue in Bugzilla every day and filter by your account to see all requests that have been submitted for you. Requests for P1/P2 bugs should recieve a response within 1 working day. All other requests should receive a response within 5 working days.

Resources

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

1. Search Mozilla’s code repositories with searchfox.
2. Mercurial for Mozillians.
3. Textbook about general open source practices: Practical Open Source Software Exploration
4. If you’d rather use git instead of hg, see git workflow for Gecko development and/or this blog post by :ato.
5. A mercurial firefox cheat-sheet with helpful commands that are used often.