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

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.

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

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

Mailing Lists

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

Chat

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:

echo 'ac_add_options --enable-project=comm/mail' > mozconfig

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 recommended that you only use options that you fully understand. Here are come recommended options to use and why:

• To create a debug build instead of a release build: ac_add_options --enable-debug

• To speed up subsequent builds by caching compilation results for both C++ and Rust: ac_add_options --with-ccache=sccache

• To enable some additional checks we have enabled in the CI: ac_add_options --enable-clang-plugin

• To enable debug symbols: ac_add_options --enable-debug-symbols

• To enable autoclobber: mk_add_options AUTOCLOBBER=1

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

Building

./mach build

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:

./mach run

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:

hg pull -u
cd comm
hg pull -u
cd ..

or to do it via one command:

hg pull -u; (cd comm; hg pull -u)

Rebuilding

To build after changes you can simply run:

./mach build

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:

./mach build binaries

JavaScript or XUL Files (Windows Only):

./mach build path/to/dir

./mach build comm/calendar/lightning

Build Prerequisites

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

General Information

Mercurial Version Control

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/.

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:

What's Next

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

In the first part of this tutorial, we will create a very simple extension, which adds a "Hello World" button to Thunderbird's main toolbar and a click on it will show a Hello, World! popup.

Creating a manifest.json

First, we create an empty hello-world project folder for our extension and navigate to it.

Extensions require a manifest.json file that tells Thunderbird a few basic information about the add-on. Let's place the following manifest.json file directly in the hello-world project folder.

{
    "manifest_version": 2,
    "name": "Hello World Example",
    "description": "A basic Hello World example extension!",
    "version": "1.0",
    "author": "Thunderbird Team",
    "browser_specific_settings": {
        "gecko": {
            "id": "helloworld@yoursite.com",
            "strict_min_version": "128.0"
        }
    },
    "browser_action": {
        "default_popup": "mainPopup/popup.html",
        "default_title": "Hello World",
        "default_icon": "images/internet-32px.png"
    },
    "icons": {
        "64": "images/internet.png",
        "32": "images/internet-32px.png",
        "16": "images/internet-16px.png"
    }
}

Using a browser_action

The above manifest includes the definition for a browser_action. That is the button we want to add to Thunderbird's main toolbar. The reference to a browser in its name is inherited from the Firefox Browser.

popup.html

The location of the HTML file loaded by the popup of our browser_action is defined in the browser_action.default_popup key. Let's create a mainPopup directory in the hello-world project folder for everything related to that popup and start with the following popup.html .

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">
    <title>Hello World</title>
    <link rel="stylesheet" type="text/css" media="screen" href="popup.css">
</head>

<body>
    <div class="popup-page">
        Hello, World!
    </div>
    <script type="module" src="popup.js"></script>
</body>

</html>

popup.js

We're going to create the following file called popup.js and place it in the same folder as the popup.html file.

// Below is what we'll log to the console.

console.log('Hello, World! - from popup.js');

What our little script does is sending a message to the console each time we click on our "Hello World" toolbar button. We'll take a look at that in a moment when we try out our add-on. The first line is just a comment, so we can remember what our code is doing.

popup.css

Now we want to create the CSS file referenced in our HTML file. We'll call it popup.css. This is just for decoration of the page, we'll put it in the same folder as the popup.html file.

.popup-page {
    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
    font-weight: bold;
    height: 60px;
    padding: 10px;
}

Testing the Extension

hello-world/
  ├── manifest.json
  ├── images/
      ├── internet.png
      ├── internet-16px.png
      └── internet-32px.png
  └── mainPopup/
      ├── popup.css
      ├── popup.html
      └── popup.js

Installing

To install the add-on we created, we are going to load it temporarily. Let's start by opening the Add-ons Manager:

This will open up the Add-ons Manager, make sure "Extensions" is selected on the left-hand side and click the gear to select "Debug Add-ons".

Click on the "Load Temporary Add-on..." button:

Select the manifest.json file from within our hello-world project folder:

This should install the add-on for this session only:

Opening the Error Console

Our extension will print messages to the error console using console.log(), so we need to open the error console first, in order to see those log entries. Hit the "Inspect" button under the add-on's listing (pictured above), this will open the Developer Tools window.

Make sure the "Console" tab is selected in the Developer Tools. Click the "Persist Logs" checkbox in the top right-hand corner of the Developer Tools window so that we can see the output from the add-on after we've interacted with it (otherwise, it only shows output as it is happening).

Trying it Out

Now we can give our new add-on a whirl. Head to the home tab and find the new "Hello World" button in the main toolbar in the top right-hand corner. Click on it to see a popup with the Hello, World! message.

Now, if you look at the Developer Tools window, you should see something like the following in the console:

Creating the add-on file

Once the add-on is ready for release or if you want to share it with others, you need to create a single add-on file. Simply zip the content of the add-on's project folder and use the xpi file extension. That file can be installed from the gear menu in the Thunderbird Add-ons Manager.

Getting Started

There are many ways to get involved in Thunderbird. You don't need to be a highly experienced software developer to be part of our welcoming contributor community. There are ways that anyone can participate so find an area that works for you and dive right in!

Improving documentation

Perfect documentation doesn't exist and there is always room for improvement. If you read through any of our documentation and notice a typo, or something that is unclear, or some section you feel is missing.. feel free to add it or tell us about it.

User support

Beta testing

We always need more beta testers to let us know if something is not working (by filing bugzilla issues) before we release a given version. This is a great place to start contributing if you're not sure where to jump in.

Filing bugs

If you are using any version of Thunderbird and you encounter something you feel is not working properly, let us know in a bugzilla issue.

Triaging bugs

When a new bug is filed, it's status is UNCONFIRMED. This means the issue has not been triaged (verified that the bug in fact does exist) by someone else other than the bug reporter. If an issue exists only for one person (i.e. the bug reporter), the problem is likely localized to that person's environment in some way and is not an actual Thunderbird code issue. That is why it is very helpful for another person (i.e. yourself) to see if the issue can be reproduced and make sure the issue has reproducer steps and information about the environment where it was reproduced (version of Thunderbird, operating system, etc.).

The number of people triaging new bugs is low and that makes it hard to keep up with the new incoming bugs every day. Your help would be greatly appreciated!

Code patches

If you want to fix a bug or add a feature, the way to do it is through direct code contributions.

I'm stuck and need help!

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).

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:

• 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.

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

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:

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

Ubuntu/Debian

Fedora

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

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 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

You're all set

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

brew install python pipx

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.

pipx install MozPhab
pipx ensurepath 

Mercurial

brew install 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

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

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 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

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

You're all set

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++.

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.

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.

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.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.

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

The Account Manager

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 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 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 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

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).

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.

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.

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.

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 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.

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.

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.

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

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

During installation make sure the following workloads are checked:

• "Desktop development with C++"

• "Game development with C++"

MozillaBuild Package

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 "Setting up a build environment" page:

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

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)

Protocol Interfaces

Protocols are implemented in chat core using JavaScript.

Useful Code

Example Implementations

• 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);

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

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

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

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.

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

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:

mk_add_options MOZ_OBJDIR=obj-artifact
ac_add_options --enable-artifact-builds

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:

try: -b o -p linux64,macosx64-shippable,win64 -u all --artifact

(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.

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:

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:

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:

In context:

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:

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.

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.

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 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 you can’t find a regression, add the regressionwindow-wanted keyword.

The Bug is NOT REPRODUCIBLE

• 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.

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.

• 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.

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

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:

  A -> B -> C -> D -> E

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:

  A -> B -> F -> G -> H
        \
         C -> D -> E

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:

  A -> B -> F -> G -> H -> C2 -> D2 -> E2

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:

<<<<<<< local
        // These are lines that were changed by changeset H!
        anAwesomeFunction(foo);
=======
        // But in changeset D they were changed in a different way!
        anEndearingFunction(bar);
>>>>>>> other

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.

For JavaScript code we use both:

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

Via the Command Line

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:

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

• VS Code plugin by Esben Petersen

• VS Code plugin by Dirk Baeumer

More Details

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.