Hardware Requirements

64-bit version

You will need to be running a 64-bit version of Linux in order to build Thunderbird. You can check which version you're running by typing this command in your terminal:

uname -m

if this command returns x86_64 you can proceed.

30 GB of free space

The Thunderbird build can use 30-40GB of disk space to complete depending on your operating system.

Build Environment

Python

You’ll need Python 3.8 or later installed.

You can check with python3 --version to see if you have it already. If not, you can install it with your distribution’s package manager. Make sure your system is up to date!

You will also need python3-distutils and python3-pip installed from your distribution's package manager.

Mercurial

As noted in the Getting Started page, both mozilla-central and comm-central are repositories using the Mercurial version control system. This means you will need to install Mercurial. Here are the quick commands to use for common Linux based operating systems but for a more complete list of instructions (if neither of these works for your use case), please see Mercurial's download page on their wiki.

Ubuntu/Debian

sudo apt install mercurial

Fedora

sudo dnf install mercurial

Getting the Code

Once you have Mercurial installed, you are ready to grab the source code. There are a couple of different methods to do this.

Scripted

The bootstrap.py script will grab the two source repos you need, run ./mach bootstrap for you, and sets up a necessary mozconfig file. Download this file to the directory where you would like your source code folder to live, either by clicking the link and moving the file to the appropriate location or using wget. Then make it executable and run it.

mkdir tb-build && cd tb-build
wget https://hg.mozilla.org/comm-central/raw-file/tip/python/rocboot/bin/bootstrap.py
chmod +x bootstrap.py
./bootstrap.py

This will create a mozilla-unified directory with both a mozconfig and a comm/ folder inside. The mozconfig file is setup to build Thunderbird and you can verify this with cat mozconfig; the --enable-project parameter should be comm/mail:

ac_add_options --enable-project=comm/mail

Manually

If you would rather manually gather the source code, perform the bootstrap, and create your mozconfig file, then follow these steps.

Checkout the Source Code

Get the latest Mozilla source code from Mozilla's mozilla-central Mercurial code repository, and check it out into a local directory source (or however you want to call it). Then, get the latest Thunderbird source code from Mozilla's comm-central Mercurial code repository. It needs to be placed inside the Mozilla source code, in a directory named comm/:

hg clone https://hg.mozilla.org/mozilla-central source/
cd source/
hg clone https://hg.mozilla.org/comm-central comm/

Create mozconfig file

This step will need to be performed if you manually checked out the code and performed the bootstrap, and it will covered in the next section you follow, Building Thunderbird.

Mach Bootstrap

In the source directory run the following command to get additional dependencies needed to install Thunderbird:

./mach bootstrap

You will be presented with the following options:

Please choose the version of Firefox you want to build:
  1. Firefox for Desktop Artifact Mode
  2. Firefox for Desktop
  3. GeckoView/Firefox for Android Artifact Mode
  4. GeckoView/Firefox for Android

Please choose option 2 to proceed with a successful build.

This action should install all the remaining libraries and dependencies necessary to build Thunderbird locally.

Missing libraries

It could happen that some libraries will not be installed by the bootstrap command, specifically those related to the Rust programming language. Check whether these packages are available in your system by running these commands in your terminal:

• which rustc

• which cargo

If one or both commands return an empty output, you need to install them manually:

• Install Rust and cargo (the Rust package manager): curl https://sh.rustup.rs -sSf | sh

• Install cbindgen (tool that generates C bindings from Rust code): cargo install cbindgen

export PATH=$HOME/.cargo/bin:$PATH

You're all set

Go back to the Building Thunderbird page and continue following the guide.

The Basics

64-bit Windows

You will need to be running a 64-bit version of Windows in order to build Thunderbird. To check this in Windows 10, open the start menu and click on the gear icon on the left-hand side of the menu. This will open up the "settings" window. Click on the "System" option and then scroll down to "About". Click on the "About" option and on the new screen next to "System Type" you should see: "64-bit operating system"

Visual Studio

In order to get the necessary libraries in order to build Thunderbird, you will need to install Visual Studio - an IDE from Microsoft. Download the free community edition here.

During installation make sure the following workloads are checked:

• "Desktop development with C++"

• "Game development with C++"

MozillaBuild Package

Finally, download the MozillaBuild Package from Mozilla. Accept the default settings, in particular the default installation directory: c:\mozilla-build\. On some versions of Windows an error dialog will give you the option to ‘reinstall with the correct settings’ - you should agree and proceed.

Getting the Code

Once you have run start-shell.bat, you will need to grab the source code if you haven't already.

Get the latest Mozilla source code from Mozilla's mozilla-central Mercurial code repository, and check it out into a local directory source (or however you want to call it). Then, get the latest Thunderbird source code from Mozilla's comm-central Mercurial code repository. It now needs to be placed inside the Mozilla source code, in a directory named comm/ (this is inverse from Thunderbird 59 and earlier):

hg clone https://hg.mozilla.org/mozilla-central source/
cd source/
hg clone https://hg.mozilla.org/comm-central comm/

Mach Bootstrap

In the source directory run the following command to get additional dependencies needed to install Thunderbird:

./mach bootstrap

You will be presented with the following options:

Please choose the version of Firefox you want to build:
  1. Firefox for Desktop Artifact Mode
  2. Firefox for Desktop
  3. GeckoView/Firefox for Android Artifact Mode
  4. GeckoView/Firefox for Android

Please choose option 2 to proceed with a successful build.

This action will install all the remaining libraries and dependencies necessary to build Thunderbird locally.

Building Thunderbird

Now that you have the prerequisites for Windows, make sure you have the source code via the commands on the Getting Started page:

Then you can follow the instructions on the Building Thunderbird page:

I Want to Start Hacking

This page has some information on how to get plugged into the Community. If you are ready to start hacking, head over to one of the following sections.

Contributing to Thunderbird

Get all the information you need to set up your development environment and get ready to hack on Thunderbird.

Add-on Development

If you'd like to learn to develop add-ons for Thunderbird, check out our add-on documentation with examples, tips and links to relevant resources.

Report Bugs and Request Features

Bugzilla

Thunderbird uses Mozilla's Bugzilla platform to report and track bugs. The site can also be used to generate enhancement bugs, which can be used for feature requests. If you want to become a contributor to Thunderbird, you will need an account on Bugzilla as you will submit patches through this platform.

Profiling Thunderbird Performance

Creating a performance profile can be useful for developers to find the causes of high CPU load or slowness in Thunderbird.

Thunderbird on GitHub

If you want to contribute to the Thunderbird website, this documentation, or addons.thunderbird.net - you can find those repositories and their issue trackers on the Thunderbird GitHub page. You'll need a GitHub account to contribute there.

Getting Plugged into the Community

We have a complete listing of the ways in which you can get involved with Thunderbird on our website. Below are some quick references from that page that you can use if you are looking to contribute to Thunderbird core right away.

Mailing Lists

If you want to participate in discussions about Thunderbird development, these are the main channels.

1. TB-Planning: This mailing list is higher level topics like: the future of Thunderbird, potential features, and changes that you would like to see happen. It is also used to discuss a variety of broader issues around community and governance of the project.

2. Topicbox: A moderated mailing list for discussing engineering plans for Thunderbird. It is a place where you can raise questions and ideas for core Thunderbird development.

3. Add-on Developers: A list for Thunderbird add-on developers and aspiring add-on developers to ask questions and share knowledge.

Chat

If you want to ask questions in real-time about how to hack on Thunderbird, you can join our development chat channel at #maildev:mozilla.org

Build Prerequisites

Before you can build Thunderbird, please follow your platform's build prerequisites page:

• Windows Build Prerequisites

• Linux Build Prerequisites

• macOS Build Prerequisites

General Information

Mercurial Version Control

Mozilla uses the Mercurial version control software to propose, review, incorporate, and log changes to its code. In order to contribute to Thunderbird, you will need to be able to use this software.

Information for how to install Mercurial is available via the download page on their wiki.

Mozilla Code Base

mozilla-central vs. comm-central

The latest Mozilla source code comes from Mozilla's mozilla-central Mercurial code repository, often called source/ but it can be named anything you like. The latest Thunderbird source code comes from Mozilla's comm-central Mercurial code repository and needs to be placed inside the Mozilla source code, in a directory that must be named comm/.

Mozilla-central will build Firefox without the comm-central repo present and a few options set (detailed on the Building Thunderbird page).

Additional Documentation

Thunderbird is built on the Mozilla platform, the same base that Firefox is built from. As such the two projects share a lot of code and much of the documentation for one will apply, in many ways, to the other. If at any point you are looking for answers that you can't find here, here are some additional useful resources:

• Thunderbird Source Tree Documentation

• Firefox Source Tree Documentation

• Mozilla's Developer site called: MDN

What's Next

If you have already gone through the relevant build prerequisite steps, then let's build the latest Thunderbird:

Hardware Requirements

• At least 4 GB of RAM. 8 GB or more is recommended. While you can build Thunderbird on older hardware it can take quite a bit of time to compile on slower machines with less RAM.

• 30 GB of free space. The Thunderbird build can use up to 30-40GB of disk space to complete depending on your operating system.

• Good internet connection for the initial source download.

Build Prerequisites

Depending on your Operating System you will need to carry out a different process to prepare your machine. So first complete the instructions for your OS and then continue following these build instructions.

Build Configuration

To build Thunderbird, you need a file named mozconfig in the root directory of the mozilla-central checkout that contains the option comm/mail enabled. If you do not already have this file, then you can create it with this line by doing this in the source/ directory:

If you omit this line, the build system will build Firefox instead. Other build configuration options can be added to this file, although it's strongly recommended that you only use options that you fully understand. For example, to create a debug build instead of a release build, that file would also contain the line:

Each of these ac_add_options entries needs to be on its own line.

Building

Building can take a significant amount of time, depending on your system, OS, and chosen build options. Linux builds on a fast box may take under 15 minutes, but Windows builds on a slow box may take several hours.

Make Your Build Faster

Running Thunderbird

To run your build, you can use:

There are various command line parameters you can add, e.g. to specify a profile.

Various temporary files, libraries, and the Thunderbird executable will be found in your object directory (under comm-central/), which is prefixed with obj-. The exact name depends on your system and OS. For example, a Mac user may get an object directory name of obj-x86_64-apple-darwin10.7.3/.

The Thunderbird executable in particular, and its dependencies are located under the dist/bin folder under the object directory. To run the executable from your comm-central working directory:

• Windows: obj-.../dist/bin/thunderbird.exe

• Linux: obj-.../dist/bin/thunderbird

• macOS: obj-.../dist/Daily.app/Contents/MacOS/thunderbird

Update and Build Again

To pull down the latest changes, in the mozilla directory run the following commands:

or to do it via one command:

Rebuilding

To build after changes you can simply run:

Rebuilding Specific Parts

If you have made many changes, but only want to rebuild specific parts, you may run the following commands.

C or C++ Files:

JavaScript or XUL Files (Windows Only):

Building everything can take a long time, and in many cases is completely unnecessary. If the changes you are making are limited to the UI, or tests, or even some back-end things, then compiling and linking the unchanged C++ and Rust code produces the same results every time. So let's get someone else to do it for us.

This the idea behind artifact builds. Instead of spending our time doing the building, we instead download pre-built copies of those parts (the "binary components") from the build infrastructure. Then we build everything else (what we're interested in) around them. This can reduce time spent from hours to a few minutes.

There is a number of important caveats, so make sure you understand them before going on.

When can I use an artifact build?

In the simplest terms, if the code you are changing appears as plain-text in the final built output, you can use an artifact build. This includes:

• Javascript

• CSS

• XUL

• HTML

• Pre-processed versions of any of the above

• Any support files such as images

When can't I use an artifact build?

You can't use an artifact build if the code you are changing includes:

• C or C++

• Rust

• IDL interfaces if the binary components use the interface

• Statically-linked component .conf files (even if the component is written in JS)

• Some types of build configuration changes

• … and probably others

Modifying your build setup

How you set up to build depends on your scenario. Many people will still need to do a complete build sometimes. In this case, make a copy of your existing mozconfig file and add these lines:

Line 1 ensures your artifact build goes in a separate object directory. Don't use the same object directory for both types of builds. Line 2 enables artifact building.

From here, remember to make sure you're using the right mozconfig (export MOZCONFIG=/path/to/artifact.mozconfig).

If you don't need to do a complete build, you can just add line 2 to your existing mozconfig.

Building the right thing

As stated earlier, the build process downloads the binary components from the build infrastructure. Here's where things can get a little bit messy.

First, things can only be downloaded if they exist. So you need to make sure what you want is available. Mach will download from the latest successful non-nightly build that matches your current comm-central tree. This might not be the one you expect.

Example: if your platform is 64-bit Linux and your tree was up-to-date at this point, which build will you get?

In this example you have a choice:

• wait for the running build to complete (that is, the B to turn green, you don't need to wait for the tests) before building locally

• build now, from the last successful build and hope the changes that have landed since don't affect you

• "update" your trees back to their state when the last successful build happened

Updating to the right revision

To find the revisions used for a successful build, click on the B, and go down to the bottom of the Job Details tab:

Update both comm-central and mozilla-central trees using hg update -r abcdef1234 before building. In general, when a new build begins on the build infrastructure, it uses the latest mozilla-central as well as the latest comm-central, but that may no longer be the case by the time you build.

Other tips

• The build process logs a lot about what it's doing. This can help you understand exactly what's going on so read it the first few times you build.

• You can in many cases do an even quicker rebuild (for example to remake pre-processed files) by running ./mach build faster (or ../mach build -C . faster if your current directory is comm-central). This skips a bunch of steps at the beginning and end of the build process that you might not need. When in doubt, don't build faster.

• Calendar is built differently in an artifact build but this shouldn't affect most people.

Artifact builds on the Try server

To do an artifact Try run, add --artifact to your try syntax. For example:

(Debug builds also work but you'd specify just macosx64 in that case.)

You can (and should in a lot of cases) specify a mozilla-central revision to build from, by editing the file .gecko_rev.yml, replacing default with the revision you need. If you don't, the Try server will use the latest mozilla-central revision, which may or may not be the same one used for the latest comm-central build.

Overview of Comm Central

The following directories are included in the comm-central repository:

build Miscellaneous files used by the build process.

calendar The calendar component of Thunderbird (formerly known as the Lightning extension).

chat Files for the chat component of Thunderbird. There is also related code in mail/components/im.

The subdirectories are:

• components Various chat features, includes the interfaces that each protocol must implement.

• content User interface files which become chrome://chat/content/….

• locales The user-visible strings, in US English. Files from this directory become chrome://chat/locale/….

• modules JavaScript modules that are specific to chat.

• protocols Various protocol implementations. Each of subdirectory implements a protocol to the interfaces found under components.

• themes Common and platform-specific styling specific to chat. Files from this directory become chrome://chat/skin/….

mail Thunderbird specific source code. It's no coincidence that this folder is laid out a lot like the browser and toolkit directories on mozilla-central. Many of the subdirectories follow the same pattern:

• content User interface files which become chrome://messenger/content/….

• modules Javascript modules which become resource:///modules/….

• test Mochitest and/or XPCShell tests.

The subdirectories are:

• actors Modules which handle communication between processes. See the Firefox documentation for information about actors.

• app Configuration and packaging instructions. Contains all-thunderbird.js, the default preferences.

• base The main mail window and several miscellaneous dialogs. Also, things which are common to many parts of the program.

• branding Icons and imagery.

• components Various Thunderbird features, including:

  • accountcreation The account setup wizard.

  • addrbook The address book user front end. (Not the address book back end, which is in mailnews/addrbook).

  • cloudfile The cloud attachment feature (a.k.a. FileLink).

  • compose Email composition window.

  • extensions WebExtensions schema and implementation.

  • im The chat front end.

  • preferences The preferences tab.

• config Build instructions, including the automation mozconfig files.

• extensions

• installer Packaging and installation instructions.

• locales The user-visible strings, in US English. Files from this directory become chrome://messenger/locale/….

• modules Shared JS modules. Files from this directory become resource:///modules/….

• test The MozMill user interface tests and the code to run that test suite.

• themes Common and platform-specific styling of Thunderbird user interface. Files from this directory become chrome://messenger/skin/….

mailnews Source code specific to the Mail and Newsgroups part of Thunderbird and SeaMonkey.

mozharness Files needed for Thunderbird's test infrastructure.

other-licenses Code that is not under the Mozilla license. See http://www.mozilla.org/MPL/ for more info.

suite SeaMonkey-specific source code. Not used in Thunderbird.

taskcluster Files needed for Thunderbird's build infrastructure.

testing Files needed for Thunderbird's test infrastructure.

third_party Libraries developed elsewhere that are included in Thunderbird

Chat Core is the code for instant messaging that is used by Thunderbird. It provides a number of functions and capabilities, including:

• Account configuration

• Message logging

The Chat Core code used by Thunderbird has some abstractions to deal with the differences between protocols (e.g. IRC vs. XMPP).

This is a list of the available keyboard shortcuts with brief descriptions of what they do.

This is a page for documenting the notifications in Thunderbird. This is likely out of date. Notifications are grouped by interface you need to attach the observer to.

Contacts are at the heart of instant messaging, and thus the Chat Core has a way to abstract to a "person" (represented by an imIContact instance), which might connect to multiple networks, etc.

Display Name

The display name used in the buddy list window or in conversations can come from several sources, by precedence order:

• User-set alias, stored locally (set when the user renames someone from Thunderbird)

• Server-stored alias (some protocol store the aliases online)

• Display name / Friendly name (set by the remote contact, stored on the server)

• Username, the unique identifier of the buddy for this protocol. Can be numbers (e.g. ICQ, QQ), email addresses (e.g. MSN, XMPP) or some other string.

Possible storage locations:

• mozStorage (the file blist.sqlite)

• chat core (cached copy)

• server read/write (server-stored alias)

• server read only (display names)

Hello World

Learn to do a simple Hello World example that will introduce you to the basics of navigating the Thunderbird code and making simple changes to the application's UI.

Thunderbird Live Development Videos

This page describes the classes and interfaces involved in configuring mail accounts.

The Account Manager

The account manager controls the objects described here. It is defined by nsIMsgAccountManager and implemented by nsMsgAccountManager.

To get to the account manager from JS, use MailServices.accounts. To get to it from C++, use mozilla::components::AccountManager::Service(). (The rest of this page will describe things in JS terms only for ease of reading.)

Accounts

Accounts are simple containers for incoming servers and identities. The are defined by nsIMsgAccount and implemented by nsMsgAccount. If you're looking to use something in a mail account, you'll probably first get a reference to an nsIMsgAccount.

Accounts are identified by a key property, which is the word account and then a number. Preferences for an account have the prefix mail.accounts.accountX .

All accounts can be found at MailServices.accounts.accounts. To get a particular account, use MailServices.accounts.getAccount(accountKey).

Incoming Servers

Incoming Server objects describe a connection to a mail server, e.g. an IMAP or POP3 server, or for local mail. They are defined by nsIMsgIncomingServer and a sub-interface and implementation exists for each type of server Thunderbird can connect to.

Incoming Servers are identified by a key property, which is the word server and then a number. Preferences for an account have the prefix mail.servers.serverX .

There is a 1:1 relationship between an account and an incoming server. To get to the server from an account, use the account's incomingServer property. To get the account for a server, use MailServices.accounts.FindAccountForServer(server).

All incoming servers can be found at MailServices.accounts.allServers. To get a particular server, use MailServices.accounts.getIncomingServer(serverKey).

Identities

Identities describe everything about sending mail from an account, such as the user's name and email address, which SMTP server to use, and where to put sent mail. They are defined by nsIMsgIdentity and implemented by nsMsgIdentity.

Identities are identified by a key property, which is the word id and then a number. Preferences for an account have the prefix mail.identity.idX .

Accounts can have any number of identities, although removing the last identity generally isn't allowed. Use the account's identities and defaultIdentity properties to access them.

Typically an identity belongs to only one account, although it's technically possible for it to belong to multiple accounts. Use MailServices.accounts.getServersForIdentity(identity) to get the server(s) for an identity, and go from there to get the accounts. (Yes, this is weird.)

All identities can be found at MailServices.accounts.allIdentities. To get a particular identity, use MailServices.accounts.getIdentity(identityKey).

SMTP

SMTP breaks some of the pattern you might've noticed in the previous classes. The SMTP service, MailServices.smtp or mozilla::Components::Smtp::Service(), implements nsISmtpService as SmtpService.

SMTP server configuration is kept by objects implementing nsISmtpServer as SmtpServer. They also are identified by a key property, which is the word smtp and then a number. Preferences for an account have the prefix mail.smtpserver.smtpX .

Identity objects reference SMTP servers in their smtpServerKey attribute.

All SMTP servers can be found at MailServices.smtp.servers. To get a particular server, use MailServices.smtp.getServerByKey(smtpKey).

Conversation window

This is a list of keyboard shortcuts that are available in Thunderbird with brief descriptions of what they do.

Command + F Find

Escape to put the conversation on hold

Command + W to close the current tab

Command + Shift + H for History (Show Logs)

Command + [Plus key], Command + [Minus key] - sets the Zoom level

Command + 0 - resets the zoom level to 100%. (Use the 0 key in the top row of the keyboard, not the 0 key of the numeric keypad.)

Scrolling the conversation

Shift + PgUp/PgDn scrolls a page up or down

Home/End or Alt + PgUp/PgDn scrolls to the previous/next section. Sections are

• the beginning and end of the conversation

• the beginning or end of a session (in the log viewer)

• the first non-context message

• the unread message ruler.

When the textbox is empty, the usual navigation keys (cursor keys, PgUp/Dn, ...) will scroll the conversation view also from the textbox.

Contact list

Command + Arrow Up, Command + Arrow Down to switch between conversations

Command + Shift + Arrow Up, Command + Shift + Arrow Down to switch between unread conversations

More available shortcuts are listed in the menu next to the commands.

In January 2023 the mail front-end was rebuilt from scratch, replacing what evolved from the original Netscape front-end. This is a developers' guide to the new UI.

Mail tab types

The mail front-end consists of two types of tabs (and a standalone window, more about that later) – the 3-pane tab mail3PaneTab and the message tab mailMessageTab. These are defined in mailTabs.js and provide the tabInfo objects for tabmail to control. Most code from outside the tabs will go through here in some form, although knowing the specific details should be unnecessary.

Each mail tab tabInfo object has these read-only properties:

• chromeBrowser – This is a XUL <browser> object which displays the tab's contents, either about:3pane or about:message. As with any <browser> object you can access the displayed page with the contentWindow and contentDocument properties.

• browser and linkedBrowser – Both refer to the XUL <browser> currently displaying content (an email message or a web page) to the user, or null if there isn't any.

• message – The currently displayed message as an nsIMsgDBHdr, if there is one.

• folder – The folder containing the currently displayed message, an nsIMsgFolder.

Accessing tabs

If the mail tab you're interested in is the current tab, the following properties of tabmail point to it:

• currentTabInfo – The tabInfo object described above.

• currentAbout3Pane – The window object of the page displayed in the chromeBrowser, if the current tab is a 3-pane tab.

• currentAboutMessage – The window object of the message display page, which for message tabs is the page displayed in the chromeBrowser, and for 3-pane tabs a page within that.

If it's not the current tab, you can get the tabInfo object from tabmail and use the properties listed in the previous section to access it.

Mail windows

The standalone mail window also contains a XUL <browser> displaying about:message. The browser can be accessed from the window's messageBrowser property.

about:3pane

about:3pane is the main UI that users see when Thunderbird starts: the folder pane, the thread pane, and the message pane. It lives in the tree as about3Pane.xhtml and similarly named JS, CSS and Fluent files.

Folder pane

The folder pane displays the accounts and folders within them. Various modes of display are available.

Thread pane

The thread pane displays the list of messages in the current folder, and the Quick Filter bar for filtering those messages.

Message pane

This mesage pane contains more XUL <browser>s for displaying various things:

• webBrowser – displays web content in a child process as Firefox does.

• multiMessageBrowser – displays messages if more than one is selected.

• messageBrowser – displays a single message using about:message.

Only one is visible at any given time.

Account central

If an account is selected in the folder pane instead of a folder, yet another <browser>, accountCentralBrowser – displays Account Central, a page of various things you can do in Thunderbird.

about:message

about:message is all of the UI that displays a single message, including the message headers and attachments. It is used as the message pane in about:3pane and by itself as a message tab or window. Like about:3pane it lives in the tree as aboutMessage.xhtml, aboutMessage.js, messageHeader.css and about3Pane.ftl files.

Message contents themselves are displayed in a <browser> (if you're counting, we're now three deep) which can be accessed by the content property of an about:message window.

The Chat Core code used by Thunderbird has some abstractions to deal with the differences between protocols (e.g. IRC vs. XMPP).

Protocol Interfaces

Protocols are implemented in chat core using JavaScript.

Protocols must implement the proper interfaces and be registered with the category manager in order to be found. Protocols need to implement the prplI* interfaces (this can mostly be done using jsProtoHelper). The minimum set of interfaces to implement are:

• prplIProtocol

• prplIAccount

• prplIConversation

Useful Code

• imXPCOMUtils: Additional XPCOM utilities.

• JavaScript socket: Simplified socket code.

• jsProtoHelper: Includes basic JavaScript implementations of the interfaces and some helper code.

• XML HTTP Request helper: Simplified HTTP request code

Example Implementations

The code for the JavaScript protocols we ship by default is here.

• IRC: A full implementation, including private chats and MUCs, etc.

• JavaScript Test Protocol: An extremely simple example meant to serve as test code for the interfaces.

• Matrix: An implementation that heavily depends on an external SDK.

• XMPP: A full implementation, including private chats and MUCs, etc. There are also other protocols which inherit and customize XMPP:

  • GTalk

  • Odnoklassniki

• There are also some stub implementations for protocols that Thunderbird used to support, but no longer does. These exist purely for the icons to show up and for a nice error message to appear when the account tries to connect.

Useful Code Snippets

Using Services.core.getProtocols() to list all protocols

This lists the protocol plugins that the core service knows about. You can copy the code (as it is), paste it in the error console (linebreaks will automatically be ignored) and press "Enter" to run it.

var { IMServices } = ChromeUtils.importESModule("resource:///modules/IMServices.sys.mjs");
let protocols = IMServices.core.getProtocols();
let result = "";
for (let p of protocols) {
  let proto = p.QueryInterface(Components.interfaces.prplIProtocol);
  result += proto.name + "\t\t" + proto.id + "\n";
}
console.log(result);

A bug report can be of 3 different types

1. Enhancement Bugs that are requests for new features, or modifications of existing features. Reports that the user thinks might be incorrect behavior could be classified as bugs, but if that feature behaves as intended, the request is not a bug but a RFE (Request for Enhancement).

2. Bug/Defect Broken functionality, not working properly, crashes, and pretty much anything that is not working as expected.

3. Task Limit the use of Task to meta bugs or internal efforts related to code clean up, architectural restructuring, tests or telemetry implementation. If it affects a user of a current release, it is better categorized as a Bug.

When setting a bug priority and severity classification, note that you can click on Priority in the Category section to go to the mozilla page with the different levels and when to set them.

The Bug is REPRODUCIBLE

• Move the bug into the correct component if it’s not already there.

• Mark it as NEW if it’s still UNCONFIRMED.

• Add the triaged keyword (that will require a severity level).

• Set Priority and Severity if you feel comfortable, or ask a manager or module owner to help you define those.

• Add other keywords if relevant (ux, access, perf, etc.).

• If it’s a regression, try to find the bug that regressed that feature and add it along with the REGRESSION keyword. https://mozilla.github.io/mozregression/ is a good tool for you and reporters.

  • If you can’t find a regression, add the regressionwindow-wanted keyword.

The Bug is NOT REPRODUCIBLE

• Ask the reporter to try in troubleshoot mode without any add-on.

• Ask for more info if not already provided, like OS or their particular setup.

• Try to get more clear instructions - users tend to understand better if they are asked to make a list of actions or clicks they used.

• DON’T simply write “It works for me”, that’s not helpful and it’s just noise, and it can increase the frustration of the reporter.

• Issues are very situational, as they might be caused by errors in C++, JavaScript, translation, a custom configuration from the user, or many other things.

  • For instances in which a tab is blank or something doesn’t load as expected, ask the user to check the Error Console and report any messages in there (ctrl+shift+J or cmd+shift+J for macOS)

The Bug is a DUPLICATE

• Bugzilla does a terrible job of suggesting potential duplicates when the user files a bug, so you will stumble upon the same issue reported by different users.

• Try to identify the duplicates and close them by adding the original bug that we use as a reference. Please give a reason for duping, a) to educate the user, b) so user doesn’t feel like we are just closing bugs and brushing them off. Boilerplate text:

  • This issue is being investigated in bug XXXX. If you think that bug is missing important information that will help lead to fixing or reproducing it, please add it to that bug.

Making Hello World in Thunderbird!

No project is a real project without a Hello World guide. In this guide we will create a function in JavaScript that triggers an alert that says "Hello World!" - then we will add a menu item that triggers that function. The idea is to give you a chance to dig through the code and make some fun changes beyond this guide, and learn how to change Thunderbird!

function helloWorld()

The first thing we want to do is create the function that will run and create our JavaScript alert - this alert will create a new window with our message: "Hello World!"

Open up mailCore.js - this is the file that we'll be creating our function in. You can find this file in the content folder which is here: comm -> mail -> base -> content.

We can put our function almost anywhere in this file, so long as we don't put it within another function. Take a little while to look at this file and see if you can figure out what the other functions in this file are doing. Once you've done that find the function openAboutSupport(). If you are new to programming you can find this function easily is most editors by doing a search with ctrl+f to open up a search field - you can put openAboutSupport() in there and it should highlight that function.

After you find that function place the following code below it:

function helloWorld(){
  alert('Hello, World!');
}

As noted above, this is a JavaScript function that will create an alert that will appear in the form of a window that Thunderbird generates that will say "Hello World!"

This is what it should look like in context:

function openAboutSupport() {
  let tabmail = document.getElementById("tabmail");
  tabmail.openTab("contentTab", {contentPage: "about:support",
                  clickHandler: "specialTabs.aboutClickHandler(event);" });
}

function helloWorld(){
  alert('Hello, World!');
}

Triggering Hello World

For this tutorial we are going to create a new menu item in the App Menu (often called the hamburger menu) to call our helloWorld() function in mailCore.js.

In the directory: comm -> mail -> components -> customizableui -> content - we are going to open the file panelUI.inc.xhtml and find the "appmenu_help" toolbarbutton (you'll likely want to use Ctrl+F again to find it).

Once you found the appmenu_help toolbarbutton, insert the following code below it:

<toolbarbutton id="hello_world"
               class="subviewbutton"
               label="Hello World!"
               oncommand="helloWorld();" />

In context:

<toolbarbutton id="appmenu_help"
               class="subviewbutton subviewbutton-iconic subviewbutton-nav"
               label="&helpMenuWin.label;"
               closemenu="none"
               oncommand="PanelUI.showSubView('appMenu-helpView', this)"/>
<toolbarbutton id="hello_world"
               class="subviewbutton"
               label="Hello World!"
               oncommand="helloWorld();" />

Trying it Out

Make sure all your work is saved and then you can build Thunderbird using the ./mach build command. Once you have built Thunderbird with the changes, we can use ./mach run to try out our modified version of Thunderbird.

Click to open the App Menu on the right hand side and you should see "Hello World" (pictured below):

When you click on the "Hello World" menu item, you should get an alert prompt (pictured below):

If that alert window appears when you click the menu item then it works!

What's Next

Spend some time playing around with the menu and even try experimenting with the helloWorld function. Most of all have fun and don't worry about messing things up.

If you get in trouble you can reset the repository via the commands below (in the /comm directory) - these will remove all the changes you've made:

hg update --clean

Create a Bugzilla Account

Find a Bug

Search for Code References

Debugging Core Code

Creating Patches

Configuring Mercurial

To ensure your work is correctly attributed to you, and to make the reviewer's task easier, these options should be set in your Mercurial configuration file (Mecurial.ini on Windows, $HOME/.hgrc elsewhere).

Mercurial Workflows

Commit messages

Using standard forms for commit messages not only looks better when looking at the revision logs, it also helps various automation tools parse the messages.

Commit messages should be of the form:

For follow-up commits that fix a problem with a lint test or other failure, the suggested form is:

When fixing a bug caused by a change made to mozilla-central, often referred to as "porting" a fix to Thunderbird, mention the upstream bug in the commit message like below. Doing so helps identify bugs that need uplifting to beta or release when the ported mozilla-central bug is uplifted.

Prefixing the first line of the commit message with "WIP:" marks the patch as a work-in-progress. moz-phab (see below) will pick that up and mark it as "Changes Planned".

Picking reviewers

All changes need to be reviewed before acceptance into the codebase. It can be pretty tricky to figure out who to ask for a review.

Submitting a Patch

There is a command line tool, moz-phab, which makes it easy to submit local changesets as patches.

With moz-phab you can submit local mercurial changeset(s) like this:

The start/end changesets are optional. If omitted, moz-phab will guess which one(s) you mean.

It'll ask for confirmation before uploading, so don't worry too much about accidental submissions.

moz-phab will pick the bug number out of the commit message (Bug xxxx), and link back to the bugzilla bug. If there is a reviewer (r=...), it will automatically assign them and send them a notification. You can leave the reviewer out, but then one will have to be manually assigned via the phabricator web page. If the commit message starts with "WIP:", the patch will be marked "Changes Planned".

Updating patches

It's very common for patches to require some updates before being accepted. Locally, you can use hg commit --amend to update a changeset.

Phabricator tracks uploaded patches by adding a line to the commit message:

When you submit the patch again with moz-phab, it will see that line and realise that you're updating an existing revision rather than creating a brand new one.

The Address Book code is found in two places: the UI is primarily in mail/components/addrbook, while the back end is in mailnews/addrbook. This documentation only describes the back end.

Interfaces and Classes

Address Book Manager

The address book manager is responsible for organising individual "directories" (address books), including reading the configuration from the preferences at start-up and creating the directory objects. It is defined by the interface nsIAbManager and implemented as AddrBookManager. You can get a reference to the manager at MailServices.ab.

The address book manager can get a reference to a particular directory in a number of ways:

• By URI. Registered directories have a URI defined by the type of directory and any information needed to identify an individual directory. For example jsaddrbook://abook.sqlite.

• By unique identifier (UID). For example 70139e91-37a5-47fd-8856-2f0756f43ef1.

• By location in the preferences. Directories store their preferences at ldap_2.servers.<some identifier>.

nsIAbManager also defines the DIRECTORY_TYPE constants mentioned below.

Directories

Individual address books are referred to as "directories" or "books" in the code. They implement nsIAbDirectory.

There are different implementations:

• A base class AddrBookDirectory which handles most of the implementation detail using data provided by a sub-class. It should not be instantiated directly.

• The most common type is SQLiteDirectory which, as the name implies, stores data in an SQLite database in the user profile. It inherits from AddrBookDirectory. Directories of this type have URIs with the scheme jsaddrbook, and are of type JS_DIRECTORY_TYPE.

• CardDAVDirectory extends SQLiteDirectory by adding CardDAV capabilities. Directories of this type have URIs with the scheme jscarddav, and are of type CARDDAV_DIRECTORY_TYPE.

• LDAPDirectory extends AddrBookDirectory and adds LDAP capabilities. Directories of this type have URIs with the scheme moz-abldapdirectory, and are of type LDAP_DIRECTORY_TYPE.

• nsAbDirProperty provides a base C++ implementation of nsIAbDirectory to OS-specific address books nsIAbOSXDirectory and nsAbOutlookDirectory. These are both of type MAPI_DIRECTORY_TYPE. The OS-specific types are likely to be discontinued.

• WebExtension APIs can provide contact suggestions to the user when composing messages. This is done via a ASYNC_DIRECTORY_TYPE directory.

Contacts

Directories contain contacts or "cards", which implement the interface nsIAbCard. The are accessible by the childCards property as well as methods for searching, adding, modifying, and deleting contacts. (Confusingly a "card" can also refer to a mailing list, see below.)

Contacts are implemented by AddrBookCard for all of the JS code, or nsAbCardProperty in C++.

The current implementation stores contact data as key/value pairs. Work is underway to replace this with a more capable data storage based on the vCard format.

Mailing Lists

A mailing list (or just a "list" in many places) is a collection of contacts. To be added to a mailing list, a contact must have an email address. A mailing lists can be both nsIAbDirectory and nsIAbCard, depending on the situation. Directories provide an array of their mailing lists as nsIAbDirectory with the childNodes property. They also appear as nsIAbCard in the childCards property and some of the methods that handle cards.

A mailing list can not have any childNodes of its own. However in a confusing quirk, it can have the card of another mailing list in its childCards.

Mailing lists are implemented in AddrBookMailingList.

Notifications

The address book code fires observer service notifications. The notification names should be self-explanatory.

Notifications about directories

In all cases the "subject" of the notification is the directory.

• addrbook-directory-created

• addrbook-directory-updated – the "data" contains the property that changed, and only the "DirName" property can change

• addrbook-directory-deleted

• addrbook-directory-invalidated – many contacts changed, anything storing or displaying contacts should be thrown away and reloaded

• addrbook-directory-synced – CardDAV sync succeeded

• addrbook-directory-sync-failed – CardDAV sync failed

Notifications about contacts

In all cases the "subject" of the notification is the contact, and unless otherwise stated "data" contains the UID of the directory containing the contact.

• addrbook-contact-created

• addrbook-contact-updated

• addrbook-contact-properties-updated – "data" contains a JSON-stringified object containing the old and new values of any properties that changed

• addrbook-contact-deleted

Notifications about lists

In these cases the "subject" of the notification is the list as nsIAbDirectory and "data" is the parent directory's UID.

• addrbook-list-created

• addrbook-list-updated

• addrbook-list-deleted

In these cases the "subject" is the contact in question, and "data" is the list's UID.

• addrbook-list-member-added

• addrbook-list-member-removed

Transition to vCard Storage

As mentioned above, contact properties are stored as key/value pairs. This has limitations in a modern address book:

• There's a fixed set of keys. Although there's no real restrictions on keys you could use, no user interface is available for anything outside of the known keys.

• Multiple values for the same key aren't possible. For example if a contact has three email addresses, the first two can be stored in PrimaryEmail and SecondEmail, but there's nowhere to store the third.

• Storing meta information about the values is impossible. There's no way to mark an email address as a work address or a home address, for example.

To combat this, from Thunderbird 102 contacts stored in local directories will be converted to use the industry standard vCard format. CardDAV directories already use vCard, although the data was converted to key/value pairs so the UI could use it.

LDAP and OS-specific address books will continue to use keys/values.

New interface properties

nsIAbCard gains two new members:

• supportsVCard a boolean value indicating support for vCard (or lack thereof). Only AddrBookCard objects currently support vCard.

• vCardProperties is a VCardProperties object if the card supports vCard, or null.

The VCardProperties class contains methods for parsing, manipulating, and serialising vCards. Each piece of information in a card is represented by a VCardPropertyEntry object. See VCardUtils.sys.mjs for more information.

Storage changes

In practice, we'll be storing the vCard data as just another key/value pair. The key used will be _vCard and the value will be the entire vCard.

When a card is saved to a directory, the following things happen:

• If it supports vCard, the vCardProperties member is serialised.

• If it doesn't, the existing key/value pairs are converted to a VCardProperties object, then serialised.

• Some properties are collected from the card:

  • display name (DisplayName)

  • first and last names (FirstName and LastName)

  • first and second preference email addresses (PrimaryEmail and SecondEmail)

  • nick name (NickName)

• The serialised vCard, these properties, and any key/value properties which can't be stored in a vCard are saved.

• Any key/value properties which can be stored in the vCard are abandoned. No information is lost because the values are part of the vCard.

The names and addresses stored separately are for performance reasons. The vCard is considered the true source of information.

Data conversion between keys/values and vCard

VCardUtils.sys.mjs contains a number of utility functions for converting between the storage types:

• VCardUtils.abCardToVCard converts an nsIAbCard (any implementation) into a vCard string.

• VCardUtils.propertyMapToVCard converts a Map of keys and values to a vCard string.

• VCardUtils.vCardToAbCard converts a vCard string to an AddrBookCard.

• VCardProperties.fromVCard converts vCard string to a VCardProperties object.

• VCardProperties.fromPropertyMap converts a Map of keys and values to a VCardProperties object.

• VCardProperties.prototype.toPropertyMap converts a VCardProperties object to a Map of keys and values.

• VCardProperties.prototype.toVCard converts a VCardProperties object to a vCard string.

To see exactly what fields are converted and what they are converted to, see typeMap in VCardUtils.sys.mjs.

Hardware Requirements

30 GB of free space

The Thunderbird build can use 30-40GB of disk space to complete depending on your operating system.

Build Environment

Python

Use pipx to install mozphab

MozPhab is the tool needed to interface with Mozilla's instance of Phabricator. This step is needed before the bootstrap step. Pipx is the tool that we will use to install MozPhab and then we will make sure the relevant ~/.local/bin has been added to the PATH envirnoment variable.

Mercurial

Get the Source

Once you have Mercurial and MozPhab installed, you are ready to grab the source code. There are a couple of different methods to do this.

Scripted

This will create a mozilla-unified directory with both a mozconfig and a comm/ folder inside. The mozconfig file is setup to build Thunderbird and you can verify this with cat mozconfig; the --enable-project parameter should be comm/mail:

Manually

If you would rather manually gather the source code, perform the bootstrap, and create your mozconfig file, then follow these steps.

Checkout the Source Code

Get the latest Mozilla source code from Mozilla's mozilla-central Mercurial code repository, and check it out into a local directory source (or however you want to call it). Then, get the latest Thunderbird source code from Mozilla's comm-central Mercurial code repository. It needs to be placed inside the Mozilla source code, in a directory named comm/:

Create mozconfig file

Mach Bootstrap

In the source directory run the following command to get additional dependencies needed to install Thunderbird:

You will be presented with the following options:

Please choose option 2 to proceed with a successful build.

This action should install all the remaining libraries and dependencies necessary to build Thunderbird locally.

Missing libraries

It could happen that some libraries will not be installed by the bootstrap command, specifically Rust and Go. Check if these packages are available in your system by running these commands in your terminal:

• which rustc

• which cargo

• Install Rust: brew install rust

• Install C bindings: cargo install cbindgen

You're all set

Before you Start!

You can accidentally destroy work with MQ. MQ puts you in a position where you're doing fairly complicated stuff to your uncommitted work. Certain operations make it easy to lose work. Watch your step.

Other things to keep in mind:

• Don't use MQ in a repository anyone might pull from. MQ creates temporary changesets in your repo. If someone pulls one of them, you'll never get rid of it.

• Avoid the -f option. It is sharp and can mess up your repository if used incorrectly.

• Ensure you use the latest stable release of Mercurial.

Activate the Queues Extension

To enable MQ, put this in your Mecurial.ini file for Windows or the $HOME/.hgrc file for Linux and macOS:

Don't forget the git line. This allows changing binary files in your patches. The unified line give 8 lines patch.

Create a new Patch

Create a new patch with the command hg qnew -m "Bug ###### - fixing something amazing" patch-name.. Let's quickly analyze this command:

• qnew is the command to initial a new patch.

• -m is the command that allows you to write a commit message.

• "Bug ###### - fixing something amazing." is the format we recommend using for the commit message, specifying the number of the Bug you're working on and a small description stating what you fixed.

• patch-name is, obviously, the name of your patch, and that can be anything.

Each repository has its own queue of patches managed by MQ. They're just stored as files in the .hg/patches directory under the repository.

Refresh the Code

Whenever you change something in your code, you need to trigger the hg qrefresh command in order to update your current patch with the latest changes. Do a hg diff before you issue hg qefresh to see which changes will be added to your patch. If you use multiple patches (see section below), it may be a good idea to do a hg qseries to make sure the right patch is on top. Otherwise the changes will be added to the wrong patch.

It's always good practice to check if the current changes have been properly saved in your patch by using the command hg qdiff. All the diffs will be listed in your terminal.

Note that both hg diff and hg qdiff take a -w argument to ignore white-space in case you reindented blocks and it's hard to see the net changes.

Pop and Push

If you're working on a patch and you need to pull the updates from upstream, you need to "disconnect" your patches in order to prevent merge conflicts. Here's a standard workflow you should follow:

• hg qpop -a to "pop" all your patches and revert the code base to its original status.

• hg pull -u to pull all the recent changes from upstream.

• hg qpush to apply once again your patch. Trigger this command as many times as you need in order to apply all the patches in sequence.

Managing multiple Patches

MQ allows you to work on multiple patches at once and keeping the code separate. No matter how many patches you have applied in your queue, the qrefresh command will only update the code to the patch at the top of you series.

Use the hg qseries command to visualize a list of currently applied patches and their order.

Reordering the Patches

Sometimes the queue ends up not being in the order you want. For example, maybe you've been working on two patches, and the second one (the topmost one in your queue) is ready to be pushed before the first one is.

If you have Mercurial 1.6 or newer, the best way to reorder your queue is hg qpush --move. For example:

With older Mercurial versions, you can do this:

Import a Patch into your Queue

With MQ you can import a patch into your queue, e.g. from Bugzilla. It is unapplied by default and the filename is used as the patch-name. You can directly import a Bugzilla patch by using the Bugzilla attachment URL as the argument. In that case you may also want to use -n patch-name to specify the patch name.

If you have the qimportbz extension installed, you can also import by specifying a bug number:

Workflow Overview

Here's a quick overview of a standard workflow you will be using with MQ.

Note that hg export qtip > ~/bug-123456-fix.patch is not necessary since all the patches reside in the .hg/patches directory in your repository.

If you got yourself into Trouble

If you think that something has gone wrong, do this:

First check your patch queue: hg qseries. If that looks right, do a hg diff to see the latest changes which aren't in your patch yet. You can either add them to the patch using hg qrefresh or remove them with hg revert --all. Your best friend is the hg out command, it shows all the changesets you have locally which aren't pushed to the repository yet. If for some reason you committed a patch to push it (using hg qfinish), an action that only the sheriff does, or accidentally used hg import instead of hg qimport, hg out will show changes that are not controlled by patches in a MQ. In this case you can strip all changeset hg out shows using hg strip -r with the lowest revision shown. After that, do hg update -C default.

Advanced Usage

Commands mentioned so far can be abbreviated, so hg qser, hg qref, etc.

Of course you can delete patches from your queue using hg qdelete or rename them with hg qrename. If you decide to combine patches, there is hg qfold, that will merge the first unapplied patch into the patch at the tip of your apply queue. Use with care since the merged patch will be removed and the applied patch will be irreversibly changed.

Even if you're not the sheriff, it's sometimes handy to be able to backout one or more changesets. Use:

Thunderbird's source code is linted and formatted using automated tools, which provides several benefits that include:

• ensuring a consistent formatting style across the code base

• preventing formatting issues from taking up developer time in code review

• catching problems that might otherwise go unnoticed

• making it easier for developers to write well-formatted code

Mozlint is a library that standardizes linter configuration and provides an interface for running all linters at once. It is run via mach and is run automatically by Taskcluster.

Running Linters Locally

You can run all the various linters in the tree using the mach commlint command. Simply pass in the directory or file you wish to lint (defaults to current working directory):

Configuring Mozlint for Thunderbird

Suite code

The Mozlint configuration files in comm/tools/lint are written so that they can be shared with the Seamonkey project. Thunderbird developers may want to set MOZLINT_NO_SUITE=1 in their environment so mach commlint will not check comm/suite/. Taskcluster will also set MOZLINT_NO_SUITE when running lint checks.

Taskcluster

Bookmarks are basically labels that point to a given changeset (or a given "commit" in git terminology). They can point to different changesets at different times (more on this below).

For any of the commands below, you can learn more about them by running hg commandname --help.

Working on a particular Bug or Feature

A common use case for bookmarks is for working on a given feature or bug. A bookmark is a label you use to manage your work on one bug or feature, alongside other work on other bugs or features. Here's an example.

1. Run hg pull to download the latest changes from the remote repository.

2. Run hg update tip to update your current working directory

   to the most recent changeset that you just downloaded.

3. Run the command hg bookmark some-bookmark-name to create a bookmark

   that points to the current changeset.

   Usually the name of the bookmark is related to the bug or feature you are working on.

4. Run hg bookmarks to list all of your bookmarks and see which one is currently active.

   The one you just created should now be active.

5. You can run hg log --graph or hg wip to see which bookmarks point to which changesets.

   Or you may prefer using a GUI tool like

   that provides a more graphical overview.

6. Make changes to the code until you are ready to commit them.

7. Run hg status and hg diff to check what files and changes you are about to commit.

   If you need to add a new file use hg add some-filename before committing.

8. Commit your changes with hg commit -m "Bug ##### - fixing something amazing.".

   The -m is short for --message and lets you provide a commit message for your changeset.

   "Bug ##### - fixing something amazing" is the format we recommend for the commit message,

   specifying the number of the Bug you're working on and a small description stating what you fixed.

   Use hg log --graph to see examples of commit messages.

9. Run hg log --graph or hg wip and note how the bookmark has moved to the changeset that you

   just committed.

   The active bookmark will automatically move to the most recent changeset as you commit your changes.

   That way you can make a series of commits and the bookmark will always point to the most recent one.

10. You can use hg commit --amend to modify the current changeset rather than making a new one.

Working on more than one Bug or Feature

Being able to work on more than one bug or feature, and easily switch between working on one or the other, is a typical use case for bookmarks.

Say you have been working on feature A using the bookmark feature-A as described above, but now you want to switch to working on feature B. Here is how that can work.

1. Run hg log --graph or hg wip and copy the identifying number of the first changeset

   that comes before your changesets for feature A.

   For example if you see "changeset: 26858:4a2e39cfc820",

   you can copy either the "26858" or the "4a2e39cfc820" to identify this changeset.

   Let's say we use 26858.

2. Run hg update --rev 26858 to change the state of your current working directory to that changeset.

3. Run hg bookmark feature-B to create a new bookmark to work on feature B.

   It will currently point to changeset 26858.

4. Make some changes and do one or more commits for feature B.

5. To go back to working on feature A, you run the command hg update feature-A.

   That updates your working directory to the feature-A changeset

   and makes feature-A the active bookmark.

6. Once you've made some changes and done some commits for feature A,

   you may want to go back to working on feature B.

   To do that you would run hg update feature-B.

   That updates your working directory to the feature-B changeset

   and makes feature-B the active bookmark.

Rebasing Before Submitting to Phabricator

Say you are ready to submit one or more patches. Often other changes will have landed in the Thunderbird code base since you started your work. In that case it is best to make sure that your changes will still apply to the current state of comm-central. We can do that using hg rebase.

1. Pull down any new changesets with hg pull.

2. Use hg log --graph or hg wip to see if there are new changesets and

   get the number (or the hash) of the first changeset

   from the newly pulled changesets.

   Let's say its number is 54321.

3. Rebase your branch on to the newest changeset

   with the command hg rebase -b my-bookmark-name -d 54321.

   The -b is for bookmark and the -d is for destination.

   We are rebasing the changesets from the bookmark my-bookmark-name

   onto the destination changeset 54321.

For example, you have a series of changesets like so:

Where C, D, and E are new changesets you have created, and your bookmark "my-bookmark-name" points to changeset E.

Then, after you do hg pull you have this:

Where F, G, and H are changesets that have been added to comm-central since you started working on your changes in C, D, and E.

Then, after you do hg rebase -b my-bookmark-name -d tip you have:

Where Mercurial has re-applied C on top of H, then D on top of C2, then E on top of D2.

Rebasing can be useful in other situations too. Another variation is hg rebase -s 44444 -d 54321. Where -s indicates a source changset. That will apply the source changeset on top of the destination changeset.

So, in the example above, if changeset C had the number 44444, then hg rebase -s 44444 -d 54321 would do the same thing as hg rebase -b my-bookmark-name -d 54321.

Merge Conflicts When Rebasing

What if there are "merge conflicts"? Say, in the example above, what if the same lines of a given file were changed in different ways by both changesets H and D, and Mercurial couldn't figure out what to do?

In that case, Mercurial will pause the rebase operation and guide you through the process of resolving the conflicts.

First Mercurial will tell you which files have conflicts. Open those files in your editor to fix the conflicts manually. There you will find something like the following, where you can see the two versions of the code that conflict:

Edit those lines to resolve the conflict, so that the code is what it should be after changeset D. Once all such conflicts are fixed, save the file(s).

Then back in the terminal run the command hg resolve --mark to mark the conflicts as resolved.

And then do hg rebase --continue and Mercurial will continue the rebase operation.

To get back to the state of things before the rebase operation started, do hg rebase --abort.

• Set an accurate version number, the earliest possible/likely version where it reproduces is ideal (eg. the version # of the bug causing the regression). “Trunk” or “unspec” should be changed to an actual number.

• OS should be set if the issue is OS specific. (also add to the bug summary as a keyword, eg. “Mac”)

• Summary is key. Improving the summary speeds up understandability and searchability - your improvement can save everyone valuable time. 1) remove extraneous words. 2) add key words that express how the user experiences the issue. 3) add technical/coding info if appropriate, but never remove user symptoms from the summary.

For JavaScript code we use both:

• eslint - linting tool

• Prettier - formatting tool

These tools can be used via the command line or right in your code editor.

Via the Command Line

After editing some JavaScript code, navigate to the comm/ directory. (The following commands need to be run from the comm/ directory so that Prettier will use the comm/.prettierignore file, and not the .prettierignore file in the directory just above comm/. See Prettier issue 4081.)

For a single file, run this command, which will attempt to automatically fix any linting or formatting problems:

$ ../mach lint path/to/a/file.js --fix

Or for all the files in a given directory:

$ ../mach lint path/to/a/directory/ --fix

To simply report any problems but not attempt to automatically fix them, just omit the --fix flag:

$ ../mach lint path/to/a/file.js

In a Code Editor

Most popular code editors offer plugins for eslint and Prettier. We highly recommend installing a plugin for eslint and a plugin for Prettier so you can lint and format your code as you are editing it. Issues will be highlighted as you type and you can have Prettier format your code with a few key strokes.

Here are links to plugins for various editors:

• eslint plugins for various editors

• Prettier plugins for various editors

Some of us on the Thunderbird team use the VS Code editor with these plugins:

• Prettier - Code formatter

  VS Code plugin by Esben Petersen

• ESLint

  VS Code plugin by Dirk Baeumer

More Details

• 'Linting' on firefox-source-docs

• 'Formatting JS Code With Prettier and eslint' on MDN

Chat Core uses a message style system based on HTML, JS and CSS that is very similar to the one created for Adium. If you plan to create a message style, reading the Adium documentation on the topic may be helpful -- see this tutorial and this reference sheet.

On the other hand, you may prefer to jump right in, using the default message styles as examples: https://searchfox.org/comm-central/source/mail/components/im/messages

The rest of this page includes a variety of information about the specifics for creating a message theme for Thunderbird.

Theme files

The minimal content of chrome/ is:

• Info.plist which contains metadata about the theme

• main.css

• Incoming/Content.html

The other files are optional:

• Style information in CSS files

  • main.css is the stylesheet used for the default variant of the theme, and is also included before the variant-specific stylesheet used for other variants.

  • Variants/<variant name>.css contains the stylesheet for the variant <variant name>.

• Other files used by the stylesheets (e.g. images)

• HTML files: these files are used to build the HTML markup of the conversation.

HTML Template Replacements

These labels will be replaced with message-specific data when used in HTML files bracketed by percentage signs, e.g. %chatName%.

Replacements in header and footer templates

• chatName: Title of the conversation,

• sourceName: The account used for this conversation (the local alias is used if it is set, otherwise the account name is used).

• destinationName: The name of the conversation,

• destinationDisplayName: Title of the conversation,

• incomingIconPath: URL to the buddy icon of the person you are talking to. Will fallback to "incoming_icon.png" if no icon is available,

• outgoingIconPath: Should be the URL to the buddy icon of the account used for this conversation. Currently, this always "outgoing_icon.png",

• timeOpened, timeOpened{format}: The time when the conversation started, takes an optional format argument.

Replacement in both messages and status messages

• message: The text of the message. The actual text will be wrapped in a span node, like this:

<span class="ib-msg-txt">message</span>

• time, time{format}: The time when the message was sent. Takes an optional format parameter (unfortunately, the formats supported are not the same on all the OSes as this internally calls the native strftime function of the OS),

• timestamp: The time when the message was sent, as an integer value (number of seconds since 1970). Useful to compute intervals between messages,

• datetime: The date and time when the message was sent.

• shortTime: The time when the message was sent,

• messageClasses: CSS classes that apply to the message. This can typically be used in a class attribute of an HTML node. Possible values include:

  • "action": message starting with /me,

  • "message": regular message (not status/system messages),

  • "incoming": incoming message,

  • "outgoing": outgoing message,

  • "autoreply": message sent automatically, for example to reply with an away message,

  • "event": system/status message,

  • "nick": chat message that contains your nick,

  • "error": error message (for example "<user> as cancelled the transfer of <file>"),

  • "delayed": delayed message (Currently this seems to be used only to show the recent message history when joining a Jabber chat room),

  • "notification": notification message (messages requesting the user's attention).

Replacements in messages (incoming or outgoing) only

• userIconPath: URL to the buddy icon of the person you wrote the message. Fallbacks to "Incoming/buddy_icon.png" if the icon is missing. For outgoing messages, it always uses "Outgoing/buddy_icon.png",

• sender: The name of the sender of the message: the alias if one exists, or the username otherwise,

• senderColor: The color associated with the sender of the message. In chatrooms, this will contain a color string valid in a CSS rule. In IM conversations, it will be an empty string.

• senderStatusIcon: URL of an icon associated with the current status (idle, away, offline) of the sender of the message,

• messageDirection: Direction of the message. Always "ltr",

• senderDisplayName: Currently identical to sender. Should be the server-side alias in the future,

• senderScreenName: The username of the sender of the message,

• service: Name of the protocol through which the message transited (e.g AIM, MSN, XMPP, Google Talk, ...),

• textbackgroundcolor: Should be a color string based on the formatting information included in the message. Currently, this is always "transparent".

Replacements in status messages only

• status: Should be a string indicating the nature of the event that caused this message to appear. Currently this isn't implemented, and the result is always an empty string,

• statusIcon: URL of an icon associated with the current status (idle, away, offline) of the other person in the conversation.

Info.plist Keys

The file Info.plist is a property list file containing metadata about the theme.

The following keys are used by Thunderbird:

• DefaultVariant: The name of the default variant. Optional. "default" will be used as the name if this key doesn't exist.

• MessageViewVersion: If the version number provided is >= 3, the main.css file will be used for all variants, otherwise it will be used only for the default variant (this is for compatibility with old Adium themes. In new themes, use the value 4).

• DisplayNameForNoVariant: The display name for the default variant (that is, when no variant is selected). Optional. If this key doesn't exist, a localized version of the string "Default" will be used for display in the theme selection UI.

• DisableCombineConsecutive: This will disable the use of NextContent.html/NextContext.html/NextStatus.html HTML templates. Consécutive messages won't be treated differently from other messages.

• ActionMessageTemplate: This is used to specify how action (/me) messages should be displayed. The value of this key will be used to replace %message% in Content.html, before doing the replacement. Optional. If this key doesn't exist, the default value "* %message% *" will be used.

The following keys work, but only use them if you really feel you absolutely need them, because they make it impossible for the user to select the font in the usual way via Preferences -> Content:

• DefaultFontFamily: the default font family to use for the conversation. Values in CSS stylesheet files can override this.

• DefaultFontSize: the default font size to use for the conversation. Values in CSS stylesheet files can override this.

If your theme needs to work with Adium too, you need more keys, see this page for details.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>ActionMessageTemplate</key>
    <string>&lt;span class="pseudo" style="%senderColor%"&gt;%sender%&lt;/span&gt; %message%</string>
    <key>DefaultVariant</key>
    <string>Normal</string>
    <key>MessageViewVersion</key>
    <integer>4</integer>
</dict>
</plist>

Including JavaScript in message styles

The right file to put JavaScript in a message style is inline.js. Some Adium themes use a custom Template.html file to include JavaScript in the theme or include JavaScript in other theme files, this is NOT supported in Thunderbird.

The code that you insert in the inline.js file will be executed as soon as the conversation is loaded. It is a good place to register event listeners.

DOM Mutation events are of particular interest, because they allow you to execute scripts when a new message is added. See the DOM Events documentation.

Example:

This can be placed in the file inline.js:

var body = document.getElementById("ibcontent");
body.addEventListener("DOMNodeInserted", function(aEvent) {
   if (!(aEvent.originalTarget instanceof HTMLElement))
     return;
   var node = aEvent.originalTarget;
   /* the node variable contains the inserted node,
      do something useful with it */
}, false);

Thunderbird-specific features

Below lists the known differences between message styles in Adium and in Chat Core. Keep in mind that Adium displays conversation using Webkit and that Thunderbird uses Gecko, so the rendering may differ slightly.

Files

• NextStatus.html Optional. Used for status messages that quickly follow another status message. If this file doesn't exist, Status.html will be used instead.

Info.plist keys

• ActionMessageTemplate This is used to specify how action (/me) messages should be displayed. The value of this key will be used to replace %message% in Content.html, before doing the replacement. If this key is not provided, the default value "* %message% *" will be used.

• NoScript This theme does not include an inline.js file for JavaScript.

CSS Classes

These classes can be used in the CSS files of themes.

• ib-msg-txt This class is present on all texts that are actually a message. The %message% replacement in the HTML templates actually adds a span node with this class around all messages.

• ib-img-smile This class is present on all img tags that were added in messages by the smiley system.

• ib-nick This class is present on participants' nicknames in multi-user chats (MUCs). It carries the "left" attribute when the participant has left the chatroom. You may need an !important if you wish to override the default styling of bold and coloured text. The colour hue of the nick (for use in CSS HSL colour values) is also available stored in the "nickColor" DOM attribute of the DOM element carrying the ib-nick class.

• Mozilla-specific pseudo-classes, for example: *:-moz-any-link

Unread messages ruler

The ruler that appears between read and unread messages (from Thunderbird 38) is a hr element with the id #unread-ruler. When styling it, changes which override those in the default style for this element (in conv.css) must be marked !important.

Note: it is possible to style the unread messages themselves by using a CSS sibling selector on the unread ruler.

Element IDs which must not be used by message styles

The following element IDs are used internally by Thunderbird and must not be given to any DOM elements by message styles:

• insert-before

• actual-insert

• next-messages-start

• next-messages-end

• unread-ruler

• end-of-split-block

• Chat

• ibcontent

You will see bugs that have been around for years and received very little activity, or bugs that were originally opened as means to track new features, but went out of scope as the overall direction of the project changed.

Closing those bugs will help clean up our Bugzilla searches and keep things more organized.

• Features request (RFE) that are outside our current or future scope.

• Bugs that don’t apply anymore (E.g. old address book issues, UI that has been replaced).

• Bugs left open with the intention of one day fixing it, but do not align with our scope.

This is a list of all the primary objectives and efforts that we will be working on.

Front-end Priorities

Conversation View

Priority: P1 Delivery Quarter: Q3 2025 High level objectives (non-exhaustive):

• Full thread conversation in message pane.

• Collapsible/Expandable messages.

• Thread tree visualization.

• Reply inline (optional).

Calendar UI/UX

Priority: P1 Delivery Quarter: Q2 2025 High level objectives (non-exhaustive):

• Modern event modals with flexible UI.

• Video conferencing integration.

• Maps searching integration (Google, Apple, OpenStreetMap).

• Modern HTML, markdown, plaintext editor.

• Customizable UI with sensible defaults.

• Customizable agenda and reminders.

• Better handling of unprocessed invitations.

First Time User Experience

Priority: P1 Delivery Quarter: Q2 2025 High level objectives (non-exhaustive):

• Account Hub for email, calendar, address book, feeds, and newsgroups.

• Thunderbird Sync as the first option.

• Guided discoveries of features when first accessing (welcome wizard).

• Early customization options to set the desired defaults.

• Expose important entry points like encryption and other more hidden settings.

Unified Toolbar Completion

Priority: P2 Delivery Quarter: Q3 2025 High level objectives (non-exhaustive):

• Remove old customizable UI toolbar.

• Unifying controls for spaces, standalone dialogs, and windows.

• Add overflow space.

• Add more buttons and elements (spin buttons, separators, button groups, etc).

• Menu position.

• Rows.

• Drop the App Menu!

Tabs

Priority: P2 Delivery Quarter: Q3 2025 High level objectives (non-exhaustive):

• Spaces and tabs rebuild, with each space handling their own tabs.

• Standalone windows per space without the need of having the "mail" space.

OS System Tray

Priority: P2 Delivery Quarter: Q4 2025 High level objectives (non-exhaustive):

• Same tray code for Linux, Windows, and macOS.

• Unread indicator and counter.

• Minimize to tray.

• Start minimized.

• Compose action per account.

• Open settings.

• Quit action.

Native OS Notifications

Priority: P2 Delivery Quarter: Q4 2025 High level objectives (non-exhaustive):

• Quick actions to reply, delete, mark messages.

• Pause notifications for # time.

• Manage notifications per account.

• Focus modes.

Compose Window

Priority: P3 Delivery Quarter: Q1 2026 High level objectives (non-exhaustive):

• Drop the C++ editor code.

• Implement a modern JS editor component that can be reused in calendar, tasks, and any other text area field that needs it (signature, address book notes, etc).

• Link previews.

• Rich text with advanced features.

• Markdown support and preview.

• Native emojis support (unicode).

• Mentions support.

Settings UI

Priority: P3 Delivery Quarter: Q1 2026 High level objectives (non-exhaustive):

• Modal dialog, because a settings tab doesn't make sense.

• More sections and tabs for an intuitive discovery path, drop the never ending single pages.

• All "Appearance" settings in one page, including native themes (follow system, light, dark)

• Application settings and Account settings should be in the same place.

• "Labs" section for listing experiments

Tasks

Priority: P3 Delivery Quarter: Q2 2026 High level objectives (non-exhaustive):

• Easier onboarding! Store them in the profile and sync them if there are no supported calendars.

• Use open specs to allow interoperability.

• Be opinionated with what we do here.

• Modern UI.

• Show tasks in the calendar.

• Kanban board.

• Integrate into emails, address books, and other areas.

Home Space

Priority: P3 Delivery Quarter: Q3 2026 High level objectives (non-exhaustive):

• Stats!

• Quick links to common actions.

• Summarization of accounts.

• Blog listing (feed).

• Suggested actions.

Chat Design Kickoff

Priority: P3 Delivery Quarter: Q4 2026 High level objectives (non-exhaustive):

• Create design plan

• Identify areas with technical debt

• Prioritize existing features

• Prioritize new features

Back-end Priorities

Exchange Email

Priority: P1 Delivery Quarter: Q1 2025 High level objectives (non-exhaustive):

• Full support of email operations.

• Full support of account creation.

Global Database

Priority: P1 Delivery Quarter: Q2 2025 High level objectives (non-exhaustive):

• SQLite based.

• Rust interfaces.

• Migrations.

• Rollbacks.

• Build in parallel and populate it alongside the current database.

A New Email Encryption

Priority: P1 Delivery Quarter: Q1 2026 High level objectives (non-exhaustive):

• Thunderbird should be the champion of encryption and propose a new open path.

• Making it easier for non-technical users to use a reliable encrypted solution.

Sentry

Priority: P2 Delivery Quarter: Q1 2025 High level objectives (non-exhaustive):

• Add Sentry SDK & Initialise with DSN

• Add channel/environment

• Leverage default error capturing mechanisms

• Add Custom Breadcrumb for one component

• Configure reporting

• Test

• Document for future consumption in other components

Performance

Priority: P2 Delivery Quarter: Q2 2025 High level objectives (non-exhaustive):

• Audit current startup code.

• Slowly rebuild it.

• Create performance profiles to measure startup performance impacts.

• Implement the "�start minimized" back-end.

• Take ownership of the "primary password"� process

Exchange Calendar

Priority: P2 Delivery Quarter: Q3 2025 High level objectives (non-exhaustive):

• Integrate the exchange calendar protocol.

• Use it as a way to rebuild/improve the current calendar protocol.

• Support exchange-specific features.

Exchange Address Book

Priority: P2 Delivery Quarter: Q3 2025 High level objectives (non-exhaustive):

• Integrate the exchange address book protocol (maybe it uses carddav?)

• Support exchange-specific features.

• Fetch users' profile pictures.

Exchange Graph API

Priority: P3 Delivery Quarter: Q1 2026 High level objectives (non-exhaustive):

• Audit what can be supported via GraphAPI.

• Build a parallel protocol to A/B test against EWS.

Notes

Priority: P3 Delivery Quarter: Q2 2026 High level objectives (non-exhaustive):

• Store notes in the profile and in Sync.

• HTML, markdown, plaintext editor.

• Share notes via Send.

• Copy the Google approach (create notes for this event).

• Potential Pro offering (cloud notes with shared access like Etherpad).

• Potential syncing through IMAP.

Maintenance Priorities

Support URLs

Priority: P1 Delivery Quarter: Q1 2025 High level objectives (non-exhaustive):

• Plan and implement an efficient and standard approach to links within the application

Better logging/diagnostics

Priority: P1 Delivery Quarter: Q1 2025 High level objectives (non-exhaustive):

• Implement Sentry and telemetry to capture data that will help us prioritize response to issues based on frequency.

• Add or change logging tools to make it easier for the majority of users to provide logs.

Fluent Migration

Priority: P2 Delivery Quarter: Q2 2025 High level objectives (non-exhaustive):

• Assign a small migration effort every 2 weeks to each developer.

Complete Glean testing and uplift

Priority: P2 Delivery Quarter: Q2 2025 High level objectives (non-exhaustive):

• Complete the project.

• Validation that data is being captured as expected.

• Help services consume the data.

Hardening

Priority: P2 Delivery Quarter: Q3 2025

Fuzzing and Monkey testing

Priority: P2 Delivery Quarter: Q3 2025 High level objectives (non-exhaustive):

• Work with Rob to create scripts, VMs, checking tools etc that we can have running regularly to catch edge cases much sooner without users having to experience then report.

Re-implement Movemail

Priority: P3 Delivery Quarter: Q3 2025 High level objectives (non-exhaustive):

• Reimplement the ability to use Movemail in Thunderbird.

• No account creation feature for now.

Removal of the *Overlay.js files

Priority: P3 Delivery Quarter: Q4 2025 High level objectives (non-exhaustive):

• Replace overlay files with modules and system modules.

• Defer non-DOM operations to system modules.

• Lazy load modules when needed.

Out of scope

As we focus on the P1s, we need to always account for the dozens of other features we currently ship in Thunderbird.

These features always require maintenance, regressions and security fixes, and upstream porting.

What we won't do during this cycle is adding new features or rebuilding big chunks of code outside of the prioritized components and efforts listed in the front-end and back-end tables.

These "outsiders"" listed here are a way to highlight low priority maintenance efforts that can happen during the year, but that won't (shouldn't) take us away from the top priorities.

Feeds

• Inheriting the email UI for now is acceptable.

• It needs a complete UI and UX overhaul.

Newsgroups

• Low user adoption.

• Inheriting the email UI for now is acceptable.

Add-ons page

• A very large effort that will happen in the future.

• It's tied to the website rebuild.

Address Book space

• More improvements are needed but the current state is superior to other areas.

• A substantial rebuild happened 2 years ago.

OpenPGP and S/MIME integration

• Currently in a usable and enough stable state.

• Dedicating security fixes during this cycle.

• The UI saw some improvements in the past few years.

Message Filters

• They will need to be rebuilt from scratch.

• Tied to the new database implementation for easier message move/copy handling.

Import/Export

• Sync will make the need to import/export the whole profile hopefully uncommon.

• After that we should disable exporting the entire profile because it fails when dealing with large sizes.

Account Settings

• They should be integrated into the Settings space.

• It needs a lot of UI/UX rethinking.

Improve Account Setup

Implement a more automated account setup flow with settings auto-discovery and guided setup steps.

Folders Drawer UI improvements

Default implementation of unified folder alongside the ability to manage and organize long folder lists.

Message View UI improvements

Improvements of the content rendering of single message view, better management of contacts, extra info, and attachment through bottom sheets.

Material 3

Complete adoption of the Material 3 UI toolkit.

Simplified Settings

Improvement and reorganization of the settings in order to offer simpler and more intuitive paths to customization and control.

K-9 Mail -> Thunderbird for Android

Thunderbird for Android will be released once all these major efforts are completed and the most glaring bugs and crashes are resolved in K-9 Mail.

Thunderbird for Android will not replace K-9 Mail as both app will be maintained and released at the same time and can be used in parallel.

Conversation View

Implementations of a threaded “conversation” - similar to the mobile Gmail interface.

Syncing Support

Implementation of Mozilla Accounts and Sync between Desktop and Mobile.

The Thunderbird try server works in exactly the same way to the Firefox try server with a few minor differences. The automation is based on the same hardware and tools, so there should be few differences.

Getting access to the Try Server

To use the try server, you'll need Level 1 Commit Access. You can learn more about Mozilla's commit access policies and start the process of signing up for an account here: Becoming a Mozilla Contributor.

Configure your SSH Host

You need to make sure your ~/.ssh/config is properly configured to use the correct SSH username for the Mozilla Mercurial repository.

Your SSH config file should have something like this:

Host hg.mozilla.org
  User nemo@thunderbird.net

Your User should match the SSH username that has been grante Level 1 Commit Access.

Adding Try to your Mercurial configuration

Try server has a separate repository based upon comm-central. You'll need to add the address to your Mercurial configuration file at path/to/comm-central/.hg/hgrc:

[paths]
default = https://hg.mozilla.org/comm-central
try = ssh://hg.mozilla.org/try-comm-central

You can of course access the repository via HTTP, but not push to it, hence the ssh:// address.

Pushing to Try

Having gained level 1 access and configured Mercurial, you can push to Try. In general, it's just a matter of applying your patch(es) and running hg push -r . try if you're planning to manually trigger tasks from the Taskcluster web interface.

For pushes via the command line, we recommend using the push-to-try extensions in order to simplify the commands required to automatically trigger jobs and tasks on the try server.

An example of a command to trigger all mochitest jobs for an artifact build will look like this:

hg push-to-try -s ssh://hg.mozilla.org/try-comm-central -m "try: -b o -p all -u mochitest --artifact"

Read the full list of try syntax commands to write in your commit message.

Choosing what tasks to run

You can (and should) control what testing tasks you want to run on your push. There are several methods to do so:

Try syntax

This is the easiest and most common way. A special code (known as Try syntax) is put in the commit message of the tip-most revision being pushed, for example try: -b o -p linux64 -u all creates only an "opt" build on 64-bit Linux, and runs all of the tests on that build.

Here is the Try syntax try-comm-central understands:

• -b Build type. Use o for an opt build (most common), d for a debug build, or do for both.

• -p Platform. There are five platforms. Each also has a -shippable variant, which is a complication you probably don't need to think about.

  • linux 32-bit Linux

  • linux64 64-bit Linux

  • macosx64 Mac OS (if you don't need a debug build, specify macosx64-shippable instead)

  • win32 32-bit Windows

  • win64 64-bit Windows

  • all for all platforms

• -u Unit test suites.

  • mochitest-thunderbird

  • xpcshell

  • all

• --artifact Artifact builds. See the Artifact Builds page for more information.

Try task configuration

For more control, a special file named try_task_config.json and containing a list of the tasks to run is included in one of the pushed revisions.

The contents of the file look like this:

{
  "version": 1,
  "use-artifact-builds": true,
  "tasks": [
    "test-linux1804-64-qr/opt-mochitest-thunderbird-e10s-1",
    "test-linux1804-64-qr/opt-mochitest-thunderbird-e10s-2",
    "test-linux1804-64-qr/opt-mochitest-thunderbird-e10s-3",
    "test-linux1804-64-qr/opt-mochitest-thunderbird-e10s-4",
    "test-linux1804-64-qr/opt-mochitest-thunderbird-e10s-5",
    "test-linux1804-64-qr/opt-mochitest-thunderbird-e10s-6",
    "test-linux1804-64-qr/opt-mochitest-thunderbird-e10s-7",
    "test-linux1804-64-qr/opt-xpcshell-e10s-1",
    "test-linux1804-64-qr/opt-xpcshell-e10s-2",
    "test-linux1804-64-qr/opt-xpcshell-e10s-3",
    "test-linux1804-64-qr/opt-xpcshell-e10s-4"
  ]
}

use-artifact-builds tells the Try server to do an artifact build. Set to false or remove it for a full build. See the Artifact Builds page for more information.

tasks is a list of tasks to run. In this example it's all of the 64-bit Linux tests. A 64-bit Linux build will also run, because it is required by the tasks specified.

A copy of the file with all available tests is maintained here. A typical workflow would be to copy the file into your working directory, remove the tasks you don't want to run, and commit it. For efficiency you could export the commit as a patch and import it again when needed.

To find the name of any particular task, click on existing instance in Treeherder, then look for the "job name" in the lower-left corner of the page.

Adding tasks to an empty Try run

If you commit with neither Try syntax nor a try_task_config.json file (or you want to add to an existing run), you can one or more tasks using Treeherder. Once the decision (D) task has completed, click the drop-down arrow to the right of it, and choose "Add new jobs".

Get an installable build from a Try run

When the build at https://treeherder.mozilla.org/jobs?repo=try-comm-central is complete (normally takes 1-2 hours):

• In the black header below click "Artifacts and Debugging Tools".

• Install the downloaded file.

Testing mozilla-central patches

If you have changes that affect mozilla-central, you may wish to do a Try run to check Thunderbird isn't broken. Here's how:

1. In your mozilla-central directory, apply your patch. Then run ./mach try empty to push to the mozilla-central Try repository. You'll need to know the revision number of your push, which will be in the message printed to the console.

2. Move to your comm-central directory.

3. Modify the file .gecko_rev.yml – change GECKO_HEAD_REPOSITORY to https://hg.mozilla.org/try, and GECKO_HEAD_REV to point to the revision you previously pushed to M-C's try with mach try empty.

4. Now push to try-comm-central as per usual.

You can change .gecko_rev.yml to point to any revision on the mozilla-* trees to test your comm-central patch against them.

Testing comm-beta and comm-esr patches

When doing a Try run for patches to comm-beta or comm-esr##, the steps are the same as when doing a Try run for comm-central. (For example, you do not need to change anything in your hgrc file.) The try server is smart enough to automatically detect which one to build and test. This works because of the .gecko_rev.yml file. Note that some things might not work the same way as on comm-central (e.g. the --artifact option only works on comm-central).

Bug Fixes and Submitting Patches

In this development session Alessandro creates a patch to fix issues with the dark theme on Linux and explains how to create a patch and submit it for review.

UX/UI Design Process

Alessandro walks through the design process and how mockups are made, iterated upon, and the thinking behind the process.

Folder Fixes and Searching the Codebase

In this session Alessandro works on fixing a bug with folders in Thunderbird, he also demonstrates how to search through the code in order to find what you are looking for.

Compose Window and Inspecting UI Elements

In this session Alessandro works on fixing some compose window bugs and explains how to work with the compose window interface and inspect the Thunderbird interface elements.

Changing How Attachments Work

In this session Alessandro works on changing how attachments are displayed when composing in Thunderbird.

Compose Window and Attachment UI

In this session Alessandro continues improvements to the compose windows and attachment interface. He also dives in-depth on styles and other bits that make up how the UI is built.

This is a page for documenting the notifications from Chat Core in Thunderbird. This is likely out of date. Notifications are grouped by interface you need to attach the observer to.

nsIObserverService

imIBuddy

imIContact

Note: all imIContact notifications also go to any imITag it belongs to, as well as nsIObserverService.

imITag

prplIConversation

imIConversation

imIUserStatusInfo

How to efficiently triage bugs and contribute to a clean and organized Bugzilla

Expectations

The best way to optimize your time and drive a productive triaging session is to set limited expectations, and only tackle a limited amount of bugs per day. It’s easy to feel overwhelmed after triaging 10 bugs (some of which may be difficult) and seeing that in the meantime 50 more bugs have been reported.

Try to manage your expectations and accept that what you are doing, as small as it can look, is important and vital for the success of Thunderbird.

Requirements

Not all of these are hard requirements, but some nice to have configurations that will make it easier to triage complex reports.

Rules of the Road

• Always be respectful and polite even when faced with a difficult reporter, because a) this is a customer facing environment, b) being empathetic is healthy for both you and the reporter. Doesn’t mean you have to engage with impolite reporters or accept abuse (see 3rd point below). “Thank you”, and “please”, and similar ideas go a long way to encouraging users to engage and return.

• Acknowledge the issue, e.g.: “I’m sorry you are having some issues, could you please provide me with the following information so that I can look into it…”

• Don’t accept harassment from a reporter, if they violate our community rules mark the comment as abuse and close the bug as invalid.

  • If the bug is a real issue, recreate it in a new bug. Allowing abuse in Bugzilla sets a bad precedent and is unhealthy for everyone involved and the entire community.

  • E.g.: “You guys are idiots. This is disgusting. The Thunderbird Team/you are stupid”.

• Do not drive users against developers, and do not argue with other team members in a bug. The MZLA team is to always have a united front on Bugzilla.

  • E.g. Triager finds the regression and pulls in the developer. Developer says that it was intended that this feature would work differently (or is now unsupported).

  • Another core developer joins the conversation and publicly disagrees with the previous developer’s statement.

  • Don’t argue in the bug - take it to another internal forum to discuss, come back with a united front on how to proceed.

• Don’t promote your own point of view. A triager should be unbiased - is it a bug? Is it reproducible? That’s it.

• Do not try to create a solution to the bug. Leave the ideation and implementation of a solution to the developers, designers, and product management as there are likely many considerations that go into a resolution.

• Stay neutral and take a step back when things are hard to handle. We have 20 million users, lots of bugs and lots of negativity will come in. A bug report comes from an emotional reaction, likely a negative experience. You need to detach from the emotional aspect of any bug and not escalate emotions, but also not take it as a personal attack.

How to triage

• Don’t triage bugs that you have no idea what they are. Stick to your area of expertise!

  • If you’re in the back-end, don’t try to triage front-end bugs, and vice versa.

  • No need to add noise to bugs if you have no clue what the topic or context is.

• Stick to your strengths and to the areas you worked on. Participate in the bugs that you know what the reporter is talking about and you have historical knowledge of that area.

• Point users to KB articles so they learn to use them, and hopefully are then less likely to report things that are not bugs and more likely to make good bug reports.
• Try to first reproduce the issue reported.

• Try to add all the flags and data points in one go in order to limit email noise for all the people CC’ed on those bugs.

• Don’t let your time go to waste. If you have read a bug but are unable to confirm or add significant info (you can’t reproduce, etc) - at a minimum: assign a component, a better summary, or NI or CC someone who can take a next step.

Helpful Mercurial extensions

Firefoxtree's main feature is automatic configuration of remote repository paths. The documentation doesn't mention them, but the Thunderbird repositories are mapped as well:

Getting access to comm-central

Adding the live server to your Mercurial configuration

You'll need to add the address to your Mercurial configuration file at path/to/comm-central/.hg/hgrc:

In this example we used the label live-cc but you can use whatever you like. Using the standard label default-push is not recommended – having to type the name of the repository helps prevent mistakes.

Before pushing

Is it a good time to push? The best time to push is shortly after Mozilla updates the Firefox live server. Since Thunderbird builds on top of Firefox, pushing to live then will ensure that the build will get the latest changes.

Is there a build in progress already? If there is, please wait until you're reasonably sure the first build is not broken. In most cases this means that the Linux and OS X builds (B) are complete and tests (bct, X) are starting to turn green (free from major failures).

Is the tree green? If it isn't, do not push. Pushing something on top of an already broken build wastes resources (both computing and human).

Pushing to comm-central

Having gained level 3 access and configured Mercurial, you can push to comm-central. In general, it's just a matter of applying your patch(es) and running hg push, but let's not do that right now as a series of important checks need to happen before.

Steps before pushing

These are a series of recommended steps to always go through before pushing to Live to ensure you're pushing only what you need.

Be sure your commit message is clear and has been approved during review. The standard syntax of a commit message is Bug 000000 - Description of the patch and fix. r=reviewer.

Mercurial Queues

• Run hg qpop -a to clean your local queue.

• Run hg in to check if there are updates on the live server. (This isn't strictly necessary if you always do the next step.)

• Run hg pull -u to download and apply the most recent changes.

• Reorder your queue and run hg qpush to apply only the patches you want to push to Live.

• Run hg qseries to double check your have the right patches applied.

• Run hg qfinish --applied to include all the currently applied patches in your local tree.

• Run hg out to see a list of patches that will be pushed to the Live server. Check your commit message(s) again.

• Run hg push live-cc (or any shorthand you used in your hgrc file) to push your applied patches to comm-central.

Mercurial Bookmarks

• Run hg pull to download and apply the most recent changes.

• Run hg rebase -b my-bookmark-name -d XXX to rebase your patches. Replace the XXX with the latest public revision.

• Run hg out -r my-bookmark-name to see a list of patches that will be pushed to the Live server. Check only the patches you intend to send are listed. Check your commit message(s) again.

• Run hg push live-cc -r my-bookmark-nameto push your applied patches to comm-central. Always specify a bookmark or revision to avoid sending more than one branch.

Commit message magic words

Adding some magic words to the commit message of the tip-most revision will cause the build system to do different things. Getting it wrong or making a typo will not get the desired result.

• DONTBUILD tells the build system not to build on this push. Only the decision and linting tasks will happen, unless another process comes along and starts a build, such as the Daily automatic build.

• CLOSED TREE allows you to push to a closed tree. I hope you have permission!

• a=approver You must specify who approved the changes on some trees (not comm-central).

Landing somebody else's patch

From Bugzillla

To land a patch you didn't write, e.g. from Bugzilla, you'll need to import it into Mercurial: hg import -e https://bugzilla.mozilla.org/attachment.cgi?id=0000000

Use the -e flag as above, or hg commit --amend to edit the commit message as necessary.

From Phabricator

To import a patch or patches from Phabricator, use moz-phab patch: moz-phab patch --apply-to tip --no-bookmark --skip-dependencies D000000

• The --apply-to argument adds the patch to a specific parent revision, in this case the tip revision.

• The --no-bookmark argument prevents a Mercurial bookmark from being created automatically. If you're just importing to land a patch, creating and then deleting a bookmark is just wasting your time.

• The --skip-dependencies argument imports only the patch in question. Otherwise moz-phab will attempt to import all parent and child revisions in the Phabricator stack, including revisions that may already exist on your tree (and in this case fail miserably). You may want this to happen, in which case don't use this argument.

Use hg commit --amend or hg histedit to adjust commit messages as necessary.

Using Lando

Our Phabricator installation has a system for automatically landing patches: Lando. To use it click "View stack in Lando" and follow the instructions. A few minutes may pass before an actual landing attempt happens. If it fails (usually because the patches do not apply cleanly) you'll be notified by email and will have to find a solution.

To land several patches together, create a "stack" of patches by using the "Edit related revisions…" and section in Phabricator. This can get messy so plan in advance. Check the current stack of any revision in the "Revision Contents" section of Phabricator.

After landing

If you worded your commit message correctly, a bot will post a message in your bug with a link to the changes you made, and close the bug. To prevent the bot from closing a bug, add the leave-open keyword to the bug before landing. The bot will automatically remove the checkin-needed-tb flag if it is set.

At this point you should set the Target Milestone field in the bug to the current version, which is generally, but not always, the last option for that field.

Landing a patch on beta or ESR

You do not need to land patches on beta or ESR. We have authorised people to do that for you.

Request approval on Bugzilla in the same way you request review, using the approval-comm-beta and approval-comm-esrXX flags. At an appropriate point approval will be granted (or denied!) and your patch will be landed for you. Filling out the request form, especially the "Regression bug" and "Risk" fields, will help the approver prioritize the patch.

When requesting uplift approval for a bug with multiple patches, a single request is sufficient. It's helpful to specify in the request that multiple patches are to be uplifted. Likewise, if a bug has dependencies on another bug, specifying those dependencies and what order they should be uplifted can save a lot of time.

Uplifting patches to earlier versions is for fixes to major bugs, and regressions that break the user interface. It should not be used as a shortcut to get new features to users earlier (some exceptions apply). The release channels ensure that changes are exposed to a test audience for a period of time before being shipped to all users.

The comm-esrXX repositories in particular can be difficult to uplift patches to because of code-churn since the repository was created. Sometimes it's necessary to create a patch specifically for comm-esrXX. In these cases, attach the patch in Bugzilla rather than Phabricator. The fix still needs to be applied to comm-central and comm-beta first unless the bug really only affects comm-esrXX. (Bugs that only affect comm-esrXX are actually quite rare. At some point the bug most likely was present on comm-central and was fixed.)