diff --git a/.gitbook/assets/tb-channels.png b/.gitbook/assets/tb-channels.png index e268d450..a4985610 100644 Binary files a/.gitbook/assets/tb-channels.png and b/.gitbook/assets/tb-channels.png differ diff --git a/SUMMARY.md b/SUMMARY.md index 14cf7329..68a55ad8 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -30,8 +30,6 @@ * [Bug Types](thunderbird-development/fixing-a-bug/bug-triaging/bug-types.md) * [Garbage Collection](thunderbird-development/fixing-a-bug/bug-triaging/garbage-collection.md) * [Narrow the Scope](thunderbird-development/fixing-a-bug/bug-triaging/narrow-the-scope.md) - * [Using Mercurial Bookmarks](thunderbird-development/fixing-a-bug/using-mercurial-bookmarks.md) - * [Using Mercurial Queues](thunderbird-development/fixing-a-bug/using-mercurial-queues.md) * [Lint and Format Code](thunderbird-development/fixing-a-bug/lint-and-format-code.md) * [Using ESLint to Format Javascript Code](thunderbird-development/fixing-a-bug/using-eslint.md) * [Try Server](thunderbird-development/fixing-a-bug/try-server.md) diff --git a/add-ons/mailextensions/experiments.md b/add-ons/mailextensions/experiments.md index 1a99ee50..0aa02fec 100644 --- a/add-ons/mailextensions/experiments.md +++ b/add-ons/mailextensions/experiments.md @@ -7,12 +7,12 @@ Since Experiments directly interact with Thunderbird's core functions, it is nec {% endhint %} {% hint style="info" %} -Thunderbird does contain a few useful features related to Experiments [whose documentation is no longer generated](https://bugzilla.mozilla.org/show\_bug.cgi?id=1556460#c23). Especially if you're writing an Experiment with complex interactions between the WebExtension and your Experiment, it may be helpful to read the documentation blocks within [ExtensionCommon.sys.mjs](https://searchfox.org/mozilla-central/source/toolkit/components/extensions/ExtensionCommon.sys.mjs) and possibly other modules in the same source code folder. +Thunderbird does contain a few useful features related to Experiments [whose documentation is no longer generated](https://bugzilla.mozilla.org/show\_bug.cgi?id=1556460#c23). Especially if you're writing an Experiment with complex interactions between the WebExtension and your Experiment, it may be helpful to read the documentation blocks within [ExtensionCommon.sys.mjs](https://github.com/mozilla-firefox/firefox/blob/main/toolkit/components/extensions/ExtensionCommon.sys.mjs) and possibly other modules in the same source code folder. {% endhint %} {% hint style="info" %} For reference, the parent implementations of all built-in APIs can be found in\ -[/comm/mail/components/extensions/parent](https://searchfox.org/comm-central/source/mail/components/extensions/parent). +[/comm/mail/components/extensions/parent](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/components/extensions/parent). {% endhint %} {% hint style="danger" %} diff --git a/add-ons/resources/README.md b/add-ons/resources/README.md index 78ca6061..3d417996 100644 --- a/add-ons/resources/README.md +++ b/add-ons/resources/README.md @@ -29,7 +29,7 @@ Useful resources for converting legacy extensions or for creating Experiments. | | Description | | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Searchfox](https://searchfox.org/) | An online viewer to search the Firefox code base ([_mozilla-central_](https://searchfox.org/mozilla-central/source/)) and the Thunderbird code base ([_comm-central_](https://searchfox.org/comm-central/source/)). | +| [Searchfox](https://searchfox.org/) | An online viewer to search the Firefox code base ([_mozilla-central_](https://github.com/mozilla-firefox/firefox/blob/main/)) and the Thunderbird code base ([_comm-central_](https://github.com/thunderbird/thunderbird-desktop/blob/main/)). | | [Firefox Source Tree documentation](https://firefox-source-docs.mozilla.org/) | The current Firefox code documentation, which might be needed when converting legacy extensions. | | [Thunderbird Source Tree documentation](../../thunderbird-development/codebase-overview/) | The current Thunderbird code documentation, in addition to comments in [idl files on comm-central](https://searchfox.org/comm-central/search?q=\&path=\*.idl). This is still work in progress. | | [Archived XUL and XPCOM Documentation](https://udn.realityripple.com/docs/Mozilla) |

The archived Mozilla documentation includes information about internal components and functions used by legacy extensions. Please be aware, that those pages are not maintained and are potentially outdated. Some useful direct links:

| diff --git a/add-ons/updating/tb102/adapt-to-changes-in-thunderbird-92-102.md b/add-ons/updating/tb102/adapt-to-changes-in-thunderbird-92-102.md index 817d37aa..b3dbd48e 100644 --- a/add-ons/updating/tb102/adapt-to-changes-in-thunderbird-92-102.md +++ b/add-ons/updating/tb102/adapt-to-changes-in-thunderbird-92-102.md @@ -81,7 +81,7 @@ The method to retrieve strings from the created bundle is slightly different, in ### calICalendar.\* -Since Thunderbird 96, [many calendar functions return Promises](https://searchfox.org/comm-central/source/calendar/base/public/calICalendar.idl). This includes: +Since Thunderbird 96, [many calendar functions return Promises](https://github.com/thunderbird/thunderbird-desktop/blob/main/calendar/base/public/calICalendar.idl). This includes: * `getItem()` * `addItem()` diff --git a/add-ons/updating/tb115/adapt-to-changes-in-thunderbird-103-115.md b/add-ons/updating/tb115/adapt-to-changes-in-thunderbird-103-115.md index feb58ae8..34df1483 100644 --- a/add-ons/updating/tb115/adapt-to-changes-in-thunderbird-103-115.md +++ b/add-ons/updating/tb115/adapt-to-changes-in-thunderbird-103-115.md @@ -113,8 +113,8 @@ Removed in Thunderbird 115. Can be replaced as follows: * `OS.Constants.Sys.Name` -> `Services.appinfo.OS` * `OS.Constants.Path.profileDir` -> `PathUtils.profileDir` * `OS.Constants.Path.tmpDir`-> `PathUtils.tempDir` -* `OS.File.*` -> [IOUtils.*](https://searchfox.org/comm-central/source/mozilla/dom/chrome-webidl/IOUtils.webidl) -* `OS.Path.*` -> [PathUtils.*](https://searchfox.org/comm-central/source/mozilla/dom/chrome-webidl/PathUtils.webidl) +* `OS.File.*` -> [IOUtils.*](https://github.com/thunderbird/thunderbird-desktop/blob/main/mozilla/dom/chrome-webidl/IOUtils.webidl) +* `OS.Path.*` -> [PathUtils.*](https://github.com/thunderbird/thunderbird-desktop/blob/main/mozilla/dom/chrome-webidl/PathUtils.webidl) ## Changed API diff --git a/add-ons/updating/tb68/changes.md b/add-ons/updating/tb68/changes.md index defb1f3f..bb8ced83 100644 --- a/add-ons/updating/tb68/changes.md +++ b/add-ons/updating/tb68/changes.md @@ -55,7 +55,7 @@ In order to use HTML elements in a XUL file, you must load the HTML namespace in xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"> ``` -The following list also includes deprecated elements, which could still be used but Thunderbird has already started to purge their usage. In that case you must update your overlay files which are overlaying such elements, otherwise your overlay will not be applied. Check [SearchFox](https://searchfox.org/comm-central/source) for the current state of the files you are overlaying. +The following list also includes deprecated elements, which could still be used but Thunderbird has already started to purge their usage. In that case you must update your overlay files which are overlaying such elements, otherwise your overlay will not be applied. Check [SearchFox](https://github.com/thunderbird/thunderbird-desktop/blob/main) for the current state of the files you are overlaying. {% hint style="info" %} The replacements listed here might work in subtly different ways. Check your functionality! diff --git a/add-ons/updating/tb91/changes.md b/add-ons/updating/tb91/changes.md index 298e101f..36438227 100644 --- a/add-ons/updating/tb91/changes.md +++ b/add-ons/updating/tb91/changes.md @@ -158,9 +158,9 @@ The levels `Info`, `Trace` and `Log` are actually identical. Interface has been dropped in favor of an observer based approach. See -* [https://searchfox.org/comm-central/source/mail/base/content/msgHdrView.js#379-429](https://searchfox.org/comm-central/source/mail/base/content/msgHdrView.js#379-429) -* [https://searchfox.org/comm-central/source/mail/base/content/msgHdrView.js#277](https://searchfox.org/comm-central/source/mail/base/content/msgHdrView.js#277) -* [https://searchfox.org/comm-central/source/mail/base/content/msgHdrView.js#335](https://searchfox.org/comm-central/source/mail/base/content/msgHdrView.js#335) +* [https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/msgHdrView.js#379-429](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/msgHdrView.js#379-429) +* [https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/msgHdrView.js#277](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/msgHdrView.js#277) +* [https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/msgHdrView.js#335](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/msgHdrView.js#335) ### nsIMsgFolder.listFoldersWithFlags @@ -217,5 +217,5 @@ In Thunderbird 91, this is primarily affecting pages belonging to an Add-on, lik In practical terms, this means that you may need to update your experiments: * **If you create frames in Thunderbird's UI**, these frames now need the appropriate attributes to load content in the right process. You can find an example of required changes in [the E10S compatibility commit for the CustomUI experiment](https://github.com/rsjtdrjgfuzkfg/thunderbird-experiments/commit/11232201ff437e7bb293efdcb93ecc3963a8328d#diff-41cf834ce8c3fae411d5f4c18abf8c024630074e616cf98307e582cea5362be7). -* **If you exchange raw objects between WebExtension scopes / "child" experiment code and Thunderbird / "parent" experiment code**, you need to migrate to an indirect approach, usually based on explicit message passing. Depending on the complexity of your task, this can either happen through notifyTools, a custom experiment API or through custom experiment code directly using cross-process APIs (likely either [message managers](https://searchfox.org/mozilla-central/source/dom/chrome-webidl/MessageManager.webidl) or [actors](https://firefox-source-docs.mozilla.org/dom/ipc/jsactors.html)). +* **If you exchange raw objects between WebExtension scopes / "child" experiment code and Thunderbird / "parent" experiment code**, you need to migrate to an indirect approach, usually based on explicit message passing. Depending on the complexity of your task, this can either happen through notifyTools, a custom experiment API or through custom experiment code directly using cross-process APIs (likely either [message managers](https://github.com/mozilla-firefox/firefox/blob/main/dom/chrome-webidl/MessageManager.webidl) or [actors](https://firefox-source-docs.mozilla.org/dom/ipc/jsactors.html)). * As a consequence, **if you load JavaScript modules in "child" experiment code**, you will now get separate instances of the JSM: each process has its own instance, and there could be multiple child processes. If you keep using JSMs from "child" code, you may furthermore need to manually unload these separate instances on API shutdown (`ExtensionAPI.onShutdown`), even if you use a catch-all unloading solution like CachingFix or the WindowListener API. diff --git a/releases/cadence.md b/releases/cadence.md index cabcc635..0d998be2 100644 --- a/releases/cadence.md +++ b/releases/cadence.md @@ -5,7 +5,7 @@ Thunderbird follows a release train model to ensure timely and predictable releases. This approach allows for regular feature rollouts, stability improvements, and bug fixes. ### General Release Cadence -The general release cadence consists of 4-week cycles, with each branch corresponding to a specific release channel. Each branch, starting from comm-central, is based on the previous branch. +The general release cadence consists of 4-week cycles, with each branch corresponding to a specific release channel. Each branch, starting from main, is based on the previous branch. ![](../.gitbook/assets/tb-channels.png) @@ -15,12 +15,12 @@ The general release cadence consists of 4-week cycles, with each branch correspo #### **Thunderbird Daily** - **Release Timeline**: A new major version of Thunderbird Daily begins every 4 weeks. -- **Releases**: Thunderbird Daily is automatically released on a daily basis from comm-central. +- **Releases**: Thunderbird Daily is automatically released on a daily basis from main. #### **Thunderbird Beta** - **Release Timeline**: - A new major version of Thunderbird Beta begins every 4 weeks. - - 4 weeks after Daily starts for a new version, comm-central is merged into comm-beta. + - 4 weeks after Daily starts for a new version, main is merged into beta. - **Releases**: Thunderbird Beta for this version is released weekly for the next 3 weeks. - **Beta 1**: Includes the merged code. - **Beta 2 and above**: Include any new uplifts. @@ -28,12 +28,12 @@ The general release cadence consists of 4-week cycles, with each branch correspo #### **Thunderbird Release** - **Release Timeline**: - A new major version of Thunderbird Release begins every 4 weeks. - - 3 weeks after Beta starts for a new version, comm-beta is merged into comm-release. + - 3 weeks after Beta starts for a new version, beta is merged into release. - 1 week after this merge, the monthly Thunderbird Release is published. - **Releases**: Thunderbird Release is released every 4 weeks, with point releases as needed every 2 weeks. #### **Thunderbird ESR (Extended Support Release)** -- **Release Timeline**: The code from comm-release is merged into comm-esr\ once a year. +- **Release Timeline**: The code from comm-release is merged into esr\ once a year. - **Releases**: Thunderbird ESR is released every year, typically in July, with point releases as needed every 2 weeks. --- @@ -41,9 +41,9 @@ The general release cadence consists of 4-week cycles, with each branch correspo ### **Stabilization Milestones** #### **Daily Soft Code Freeze** -- A 1-week soft code freeze occurs for comm-central prior to merging into comm-beta. +- A 1-week soft code freeze occurs for main prior to merging into beta. - During this time: - - Risky code should not land in comm-central. + - Risky code should not land in main. - Features controlled by a feature flag that were disabled in Daily should not be enabled. #### **Pre-Merge Reviews** @@ -63,7 +63,7 @@ The general release cadence consists of 4-week cycles, with each branch correspo | Thunderbird 136.0a1 starts | Jan 6 | | Thunderbird 136.0a1 soft code freeze | Jan 27–Feb 3 | | Thunderbird 136.0a1 pre-merge review | Jan 30 | -| Thunderbird merge 136.0a1 central → beta | Feb 3 | +| Thunderbird merge 136.0a1 main → beta | Feb 3 | | Thunderbird 136.0b1 | Feb 5 | | Thunderbird 136.0b2 | Feb 12 | | Thunderbird 136.0b3 | Feb 19 | diff --git a/releases/channels.md b/releases/channels.md index bdfd82fd..44ec9bfd 100644 --- a/releases/channels.md +++ b/releases/channels.md @@ -2,9 +2,9 @@ Thunderbird provides releases through four distinct channels, each serving a unique purpose. Below are the channels, their corresponding branches, and a summary of their purpose: -- **Thunderbird Daily (comm-central)**: Where development and testing begin, and new features are developed. -- **Thunderbird Beta (comm-beta)**: The monthly stabilization release. -- **Thunderbird Release (comm-release)**: The official monthly release. -- **Thunderbird ESR (comm-esr)**: The official annual extended support release. +- **Thunderbird Daily (main branch)**: Where development and testing begin, and new features are developed. +- **Thunderbird Beta (beta branch)**: The monthly stabilization release. +- **Thunderbird Release (release branch)**: The official monthly release. +- **Thunderbird ESR (esr### branch)**: The official annual extended support release. These four channels offer increasing levels of stability, increasing as code moves from Daily to Beta and being the highest in Release and ESR. diff --git a/releases/feature-flags.md b/releases/feature-flags.md index d7d661e6..3e7a6f3d 100644 --- a/releases/feature-flags.md +++ b/releases/feature-flags.md @@ -2,11 +2,11 @@ Feature Flags are used to manage features that are not yet ready for general use. Their behavior varies depending on the branch: -### **comm-central** +### **main** Feature flags are enabled once all related code for the feature have landed. -### **comm-beta** +### **beta** Feature flags remain enabled once the feature is complete unless the developers decide to temporarily pause it. -### **comm-release and comm-esr** +### **release and esr** Feature flags are disabled by default until an explicit decision is made to enable the feature for all users. diff --git a/releases/uplifting-fixes.md b/releases/uplifting-fixes.md index 430aa48b..01bf1d1c 100644 --- a/releases/uplifting-fixes.md +++ b/releases/uplifting-fixes.md @@ -9,8 +9,8 @@ Uplifts to Beta, Release, and ESR are limited to high-impact bug fixes. Features **Patches nominated for uplift should:** - Be limited to stability, security, or high-impact bugs. -- **For Beta uplifts:** Already have landed, tested, and stabilized in comm-central. -- **For Release/ESR uplifts:** Already have landed, tested, and stabilized in comm-beta. +- **For Beta uplifts:** Already have landed, tested, and stabilized in main. +- **For Release/ESR uplifts:** Already have landed, tested, and stabilized in beta. - Include tests or provide a strong justification for the absence of tests. - Not change any localizable strings. diff --git a/thunderbird-development/building-thunderbird/README.md b/thunderbird-development/building-thunderbird/README.md index 626aa6c3..0c7b36b5 100644 --- a/thunderbird-development/building-thunderbird/README.md +++ b/thunderbird-development/building-thunderbird/README.md @@ -20,7 +20,7 @@ Depending on your Operating System you will need to carry out a different proces ## 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: +To build Thunderbird, you need a file named `mozconfig` in the root directory of the firefox 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 @@ -44,7 +44,7 @@ For more info on configuration options, see the page [Configuring build options] ## Building {% hint style="warning" %} -Before you start, make sure that the version you checked out is not busted. For `hg` tip, you should see green Bs on [https://treeherder.mozilla.org/#/jobs?repo=comm-central](https://treeherder.mozilla.org/#/jobs?repo=comm-central) +Before you start, make sure that the version you checked out is not busted. For `git` tip, you should see green Bs on [https://treeherder.mozilla.org/#/jobs?repo=comm-central](https://treeherder.mozilla.org/#/jobs?repo=comm-central) {% endhint %} After you have met the [build prerequisites](./#build-prerequisites) for your OS, the build is started in the `source` directory with: @@ -71,9 +71,9 @@ 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/`. +Various temporary files, libraries, and the Thunderbird executable will be found in your object directory (under `comm/`), 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: +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` working directory: * Windows: `obj-.../dist/bin/thunderbird.exe` * Linux: `obj-.../dist/bin/thunderbird` @@ -81,19 +81,19 @@ The Thunderbird executable in particular, and its dependencies are located under ## Update and Build Again -To pull down the latest changes, in the mozilla directory run the following commands: +To pull down the latest changes, in the firefox directory run the following commands: ``` -hg pull -u +git pull --rebase cd comm -hg pull -u +git pull --rebase cd .. ``` or to do it via one command: ``` -hg pull -u; (cd comm; hg pull -u) +git pull --rebase && git -C comm pull --rebase ``` Then just run the `./mach build` command detailed in the [Building](./#building) instructions above. This will only recompile files that changed, but it may still take a long time. diff --git a/thunderbird-development/building-thunderbird/linux-build-prerequisites.md b/thunderbird-development/building-thunderbird/linux-build-prerequisites.md index beb381d9..52b68237 100644 --- a/thunderbird-development/building-thunderbird/linux-build-prerequisites.md +++ b/thunderbird-development/building-thunderbird/linux-build-prerequisites.md @@ -41,29 +41,25 @@ You can check with `python3 --version` to see if you have it already. If not, yo You will also need `python3-distutils` and `python3-pip` installed from your distribution's package manager. -### Mercurial +### Git -As noted in the [Setting up a build environment page](../setting-up-a-build-environment.md), 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](https://www.mercurial-scm.org/wiki/Download). +As noted in the [Setting up a build environment page](../setting-up-a-build-environment.md), both Firefox and Thunderbird source are stored in Git repositories. This means you will need to install Git if it is not already available. Here are some quick commands to install on common distributions: #### Ubuntu/Debian ``` -sudo apt install mercurial +sudo apt install git ``` #### Fedora ``` -sudo dnf install mercurial +sudo dnf install git ``` ## 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. - -{% hint style="warning" %} -Mozilla-central will build Firefox without the comm-central repo present and a few options set. Mozilla-central is the Firefox codebase and comm-central features the additions that turn Firefox into Thunderbird. -{% endhint %} +Once you have Git installed, you are ready to grab the source code. There are a couple of different methods to do this. ### Scripted @@ -71,20 +67,16 @@ The [`bootstrap.py`](https://hg.mozilla.org/comm-central/raw-file/tip/python/roc ``` mkdir tb-build && cd tb-build -wget https://hg.mozilla.org/comm-central/raw-file/tip/python/rocboot/bin/bootstrap.py +wget https://raw.githubusercontent.com/thunderbird/thunderbird-desktop/main/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. +This will create a `source/` directory with both a `mozconfig` and a `comm/` folder inside. -The `mozilla-unified` repository has several bookmarks (akin to a git branch) and you will by default be on the `autoland` bookmark. You will need to be on the `central` bookmark and you can change by going into this directory and changing to that bookmark: - -``` -hg up central -``` +The `source/` repository contains the Firefox source and defaults to the `main` branch. -The `mozilla-unified/comm` repository has several bookmarks and you will by default be on the `comm` bookmark. This is where you want to be, unless you are specifically working on a past ESR. +The `source/comm` repository also defaults to the `main` branch. The `mozconfig` file is setup to build Thunderbird and you can verify this with `cat mozconfig`; the `--enable-project` parameter should be `comm/mail`: @@ -98,12 +90,12 @@ If you would rather manually gather the source code, perform the bootstrap, and #### 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/`: +Get the latest Firefox source code, and check it out into a local directory `source` (or however you want to call it). Then, get the latest Thunderbird source code. It needs to be placed **inside** the Mozilla source code, in a directory named `comm/`: ``` -hg clone https://hg.mozilla.org/mozilla-central source/ +git clone https://github.com/mozilla-firefox/firefox source/ cd source/ -hg clone https://hg.mozilla.org/comm-central comm/ +git clone https://github.com/thunderbird/thunderbird-desktop comm/ ``` #### Create `mozconfig` file diff --git a/thunderbird-development/building-thunderbird/macos-build-prerequisites.md b/thunderbird-development/building-thunderbird/macos-build-prerequisites.md index 2eaa852c..c793bd62 100644 --- a/thunderbird-development/building-thunderbird/macos-build-prerequisites.md +++ b/thunderbird-development/building-thunderbird/macos-build-prerequisites.md @@ -13,7 +13,7 @@ description: >- The Thunderbird build can use 30-40GB of disk space to complete depending on your operating system. {% hint style="warning" %} -Note that while it's not technically required to have an internet connection to build, the default when building from `mozilla/comm-central` is that `--enable-bootstrap` is set so that the toolchains download automatically. If you do not have an active internet connection then +Note that while it's not technically required to have an internet connection to build, the default when building Thunderbird is that `--enable-bootstrap` is set so that the toolchains download automatically. {% endhint %} ## Build Environment @@ -39,9 +39,9 @@ pipx install MozPhab pipx ensurepath ``` -### Mercurial +### Git -As noted in the [Setting up a build environment page](../setting-up-a-build-environment.md), both `mozilla-central` and `comm-central` are version controlled with Mercurial. This means you will need to install Mercurial. Here is a quick command to install it with mercurial but for a more complete list of instructions, please see [Mercurial's download page on their wiki](https://www.mercurial-scm.org/wiki/Download). +As noted in the [Setting up a build environment page](../setting-up-a-build-environment.md), both Firefox and Thunderbird source are stored in Git repositories. This means you will need to install Git if it is not already available. Here is a quick command to install it: ``` brew install mercurial @@ -49,10 +49,10 @@ 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. +Once you have Git and MozPhab installed, you are ready to grab the source code. There are a couple of different methods to do this. {% hint style="warning" %} -Mozilla-central will build Firefox without the comm-central repo present and a few options set. Mozilla-central is the Firefox codebase and comm-central features the additions that turn Firefox into Thunderbird. +Firefox can build without Thunderbird present in the `comm/` repo and a few options set. The Thunderbird code base features the additions that turn Firefox into Thunderbird. {% endhint %} ### Scripted @@ -61,21 +61,16 @@ We have created and host a script that will grab the two source repos you need, ``` mkdir tb-build && cd tb-build -wget https://hg.mozilla.org/comm-central/raw-file/tip/python/rocboot/bin/bootstrap.py +wget https://raw.githubusercontent.com/thunderbird/thunderbird-desktop/main/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. +This will create a `source/` directory with both a `mozconfig` and a `comm/` folder inside. -The `mozilla-unified` repository has several bookmarks (akin to a git branch) and you will by default be on the `autoland` bookmark. You will need to be on the `central` bookmark and you can change by going into this directory and changing to that bookmark: - -``` -hg up central -``` - -The `mozilla-unified/comm` repository has several bookmarks and you will by default be on the `comm` bookmark. This is where you want to be, unless you are specifically working on a past ESR. +The `source/` repository contains the Firefox source and defaults to the `main` branch. +The `source/comm` repository also defaults to the `main` branch. The `mozconfig` file is setup to build Thunderbird and you can verify this with `cat mozconfig`; the `--enable-project` parameter should be `comm/mail`: @@ -89,13 +84,12 @@ If you would rather manually gather the source code, perform the bootstrap, and #### 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/`: +Get the latest Firefox source code, and check it out into a local directory `source` (or however you want to call it). Then, get the latest Thunderbird source code. It needs to be placed **inside** the Mozilla source code, in a directory named `comm/`: ``` -hg clone https://hg.mozilla.org/mozilla-central source/ +git clone https://github.com/mozilla-firefox/firefox source/ cd source/ -hg clone https://hg.mozilla.org/comm-central comm/ -``` +git clone https://github.com/thunderbird/thunderbird-desktop comm/ #### Create `mozconfig` file diff --git a/thunderbird-development/building-thunderbird/windows-build-prerequisites.md b/thunderbird-development/building-thunderbird/windows-build-prerequisites.md index 4f47805f..d328dc63 100644 --- a/thunderbird-development/building-thunderbird/windows-build-prerequisites.md +++ b/thunderbird-development/building-thunderbird/windows-build-prerequisites.md @@ -39,12 +39,16 @@ Once this is done, creating a shortcut to `c:\mozilla-build\start-shell.bat` on 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\): +The latest Firefox and Thunderbird source code is available from the main branches of the [firefox](https://github.com/mozilla-firefox/firefox) and [thunderbird-desktop](https://github.com/thunderbird/thunderbird-desktop) Git repositories, respectively. + +When building locally: +* The root of the Firefox source is often renamed to `source/` but it can be named anything you like. +* The root of the Thunderbird source needs to be placed **inside** the Firefox source code, in a directory that must be named `comm/`. ```bash -hg clone https://hg.mozilla.org/mozilla-central source/ +git clone https://github.com/mozilla-firefox/firefox source/ cd source/ -hg clone https://hg.mozilla.org/comm-central comm/ +git clone https://github.com/thunderbird/thunderbird-desktop comm/ ``` ### Mach Bootstrap diff --git a/thunderbird-development/codebase-overview/README.md b/thunderbird-development/codebase-overview/README.md index dcfc7332..f61d1c5c 100644 --- a/thunderbird-development/codebase-overview/README.md +++ b/thunderbird-development/codebase-overview/README.md @@ -6,9 +6,9 @@ description: >- # Codebase Overview -## Overview of Comm Central +## Overview of Thunderbird Source Code -The following directories are included in the comm-central repository: +The following directories are included in the [Thunderbird](https://github.com/thunderbird/thunderbird-desktop) repository: **build**\ Miscellaneous files used by the build process. diff --git a/thunderbird-development/codebase-overview/account-configuration.md b/thunderbird-development/codebase-overview/account-configuration.md index d5f15c9e..7c43a3f6 100644 --- a/thunderbird-development/codebase-overview/account-configuration.md +++ b/thunderbird-development/codebase-overview/account-configuration.md @@ -8,13 +8,13 @@ Chat accounts use very similar mechanisms, but we won't go into that here to avo ## The Account Manager -The account manager controls the objects described here. It is defined by [`nsIMsgAccountManager`](https://searchfox.org/comm-central/source/mailnews/base/public/nsIMsgAccountManager.idl) and implemented by [`nsMsgAccountManager`](https://searchfox.org/comm-central/source/mailnews/base/src/nsMsgAccountManager.cpp). +The account manager controls the objects described here. It is defined by [`nsIMsgAccountManager`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/base/public/nsIMsgAccountManager.idl) and implemented by [`nsMsgAccountManager`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/base/src/nsMsgAccountManager.cpp). 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`](https://searchfox.org/comm-central/source/mailnews/base/public/nsIMsgAccount.idl) and implemented by [`nsMsgAccount`](https://searchfox.org/comm-central/source/mailnews/base/src/nsMsgAccount.cpp). If you're looking to use something in a mail account, you'll probably first get a reference to an `nsIMsgAccount`. +Accounts are simple containers for incoming servers and identities. The are defined by [`nsIMsgAccount`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/base/public/nsIMsgAccount.idl) and implemented by [`nsMsgAccount`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/base/src/nsMsgAccount.cpp). 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` . @@ -22,7 +22,7 @@ All accounts can be found at `MailServices.accounts.accounts`. To get a particul ## 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`](https://searchfox.org/comm-central/source/mailnews/base/public/nsIMsgIncomingServer.idl) and a sub-interface and implementation exists for each type of server Thunderbird can connect to. +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`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/base/public/nsIMsgIncomingServer.idl) 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` . @@ -32,7 +32,7 @@ All incoming servers can be found at `MailServices.accounts.allServers`. To get ## 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`](https://searchfox.org/comm-central/source/mailnews/base/public/nsIMsgIdentity.idl) and implemented by [`nsMsgIdentity`](https://searchfox.org/comm-central/source/mailnews/base/src/nsMsgIdentity.cpp). +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`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/base/public/nsIMsgIdentity.idl) and implemented by [`nsMsgIdentity`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/base/src/nsMsgIdentity.cpp). 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` . @@ -44,9 +44,9 @@ All identities can be found at `MailServices.accounts.allIdentities`. To get a p ## 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`](https://searchfox.org/comm-central/source/mailnews/compose/public/nsISmtpService.idl) as [`SmtpService`](https://searchfox.org/comm-central/source/mailnews/compose/src/SmtpService.jsm). +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`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/compose/public/nsISmtpService.idl) as [`SmtpService`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/compose/src/SmtpService.jsm). -SMTP server configuration is kept by objects implementing [`nsISmtpServer`](https://searchfox.org/comm-central/source/mailnews/compose/public/nsISmtpServer.idl) as [`SmtpServer`](https://searchfox.org/comm-central/source/mailnews/compose/src/SmtpServer.jsm). 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` . +SMTP server configuration is kept by objects implementing [`nsISmtpServer`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/compose/public/nsISmtpServer.idl) as [`SmtpServer`](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/compose/src/SmtpServer.jsm). 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. diff --git a/thunderbird-development/codebase-overview/address-book.md b/thunderbird-development/codebase-overview/address-book.md index bb6ec045..12849503 100644 --- a/thunderbird-development/codebase-overview/address-book.md +++ b/thunderbird-development/codebase-overview/address-book.md @@ -101,7 +101,7 @@ LDAP and OS-specific address books will continue to use keys/values. * `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](https://searchfox.org/comm-central/source/mailnews/addrbook/modules/VCardUtils.sys.mjs) for more information. +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](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/addrbook/modules/VCardUtils.sys.mjs) for more information. ### Storage changes @@ -129,7 +129,7 @@ Cards are only migrated when they are saved. ### Data conversion between keys/values and vCard -[VCardUtils.sys.mjs](https://searchfox.org/comm-central/source/mailnews/addrbook/modules/VCardUtils.sys.mjs) contains a number of utility functions for converting between the storage types: +[VCardUtils.sys.mjs](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/addrbook/modules/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. diff --git a/thunderbird-development/codebase-overview/chat/README.md b/thunderbird-development/codebase-overview/chat/README.md index 2550ec39..4f30da83 100644 --- a/thunderbird-development/codebase-overview/chat/README.md +++ b/thunderbird-development/codebase-overview/chat/README.md @@ -9,7 +9,7 @@ Chat Core is the code for instant messaging that is used by Thunderbird. It prov * Message logging * [Emoticon (smileys) handling](broken-reference) -The Chat Core code lives in the chat/ directory of [comm-central](https://searchfox.org/comm-central/source/chat). +The Chat Core code lives in the chat/ directory of the [Thunderbird](https://github.com/thunderbird/thunderbird-desktop) repository. #### [Chat Core Protocols](chat-core-protocols.md) @@ -17,7 +17,7 @@ The Chat Core code used by Thunderbird has some abstractions to deal with the di #### [Contacts](contacts.md) -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`](https://searchfox.org/comm-central/source/chat/components/public/imIContactsService.idl) instance), which might connect to multiple networks, etc. +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`](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIContactsService.idl) instance), which might connect to multiple networks, etc. #### [Keyboard shortcuts](keyboard-shortcuts.md) diff --git a/thunderbird-development/codebase-overview/chat/chat-core-protocols.md b/thunderbird-development/codebase-overview/chat/chat-core-protocols.md index b7517b34..597d114e 100644 --- a/thunderbird-development/codebase-overview/chat/chat-core-protocols.md +++ b/thunderbird-development/codebase-overview/chat/chat-core-protocols.md @@ -6,29 +6,29 @@ The [Chat Core](./) code used by Thunderbird has some abstractions to deal with 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](https://searchfox.org/comm-central/source/chat/components/public/) \(this can mostly be done using [jsProtoHelper](https://searchfox.org/comm-central/source/chat/modules/jsProtoHelper.sys.mjs)\). The minimum set of interfaces to implement are: +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](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/) \(this can mostly be done using [jsProtoHelper](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/modules/jsProtoHelper.sys.mjs)\). The minimum set of interfaces to implement are: -* [prplIProtocol](https://searchfox.org/comm-central/source/chat/components/public/prplIProtocol.idl) -* [prplIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) -* [prplIConversation](https://searchfox.org/comm-central/source/chat/components/public/prplIConversation.idl) +* [prplIProtocol](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIProtocol.idl) +* [prplIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) +* [prplIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIConversation.idl) #### Useful Code -* [imXPCOMUtils](https://searchfox.org/comm-central/source/chat/modules/imXPCOMUtils.sys.mjs): Additional XPCOM utilities. -* [JavaScript socket](https://searchfox.org/comm-central/source/chat/modules/socket.sys.mjs): Simplified socket code. -* [jsProtoHelper](https://searchfox.org/comm-central/source/chat/modules/jsProtoHelper.sys.mjs): Includes basic JavaScript implementations of the interfaces and some helper code. -* [XML HTTP Request helper](https://searchfox.org/comm-central/source/mozilla/toolkit/modules/Http.jsm): Simplified HTTP request code +* [imXPCOMUtils](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/modules/imXPCOMUtils.sys.mjs): Additional XPCOM utilities. +* [JavaScript socket](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/modules/socket.sys.mjs): Simplified socket code. +* [jsProtoHelper](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/modules/jsProtoHelper.sys.mjs): Includes basic JavaScript implementations of the interfaces and some helper code. +* [XML HTTP Request helper](https://github.com/thunderbird/thunderbird-desktop/blob/main/mozilla/toolkit/modules/Http.jsm): Simplified HTTP request code #### Example Implementations -The code for the JavaScript protocols we ship by default is [here](https://searchfox.org/comm-central/source/chat/protocols). +The code for the JavaScript protocols we ship by default is [here](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/protocols). -* [IRC](https://searchfox.org/comm-central/source/chat/protocols/irc): A full implementation, including private chats and MUCs, etc. -* [JavaScript Test Protocol](https://searchfox.org/comm-central/source/chat/protocols/jsTest): An extremely simple example meant to serve as test code for the interfaces. -* [Matrix](https://searchfox.org/comm-central/source/chat/protocols/matrix): An implementation that heavily depends on an external SDK. -* [XMPP](https://searchfox.org/comm-central/source/chat/protocols/xmpp): A full implementation, including private chats and MUCs, etc. There are also other protocols which inherit and customize XMPP: - * [GTalk](https://searchfox.org/comm-central/source/chat/protocols/gtalk) - * [Odnoklassniki](https://searchfox.org/comm-central/source/chat/protocols/odnoklassniki) +* [IRC](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/protocols/irc): A full implementation, including private chats and MUCs, etc. +* [JavaScript Test Protocol](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/protocols/jsTest): An extremely simple example meant to serve as test code for the interfaces. +* [Matrix](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/protocols/matrix): An implementation that heavily depends on an external SDK. +* [XMPP](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/protocols/xmpp): A full implementation, including private chats and MUCs, etc. There are also other protocols which inherit and customize XMPP: + * [GTalk](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/protocols/gtalk) + * [Odnoklassniki](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/protocols/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 diff --git a/thunderbird-development/codebase-overview/chat/contacts.md b/thunderbird-development/codebase-overview/chat/contacts.md index 9f31a4a0..ec683398 100644 --- a/thunderbird-development/codebase-overview/chat/contacts.md +++ b/thunderbird-development/codebase-overview/chat/contacts.md @@ -1,6 +1,6 @@ # Contacts -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`](https://searchfox.org/comm-central/source/chat/components/public/imIContactsService.idl) instance\), which might connect to multiple networks, etc. +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`](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIContactsService.idl) instance\), which might connect to multiple networks, etc. {% hint style="warning" %} _Draft: This page is not complete._ diff --git a/thunderbird-development/codebase-overview/chat/message-styles.md b/thunderbird-development/codebase-overview/chat/message-styles.md index 56806876..436b7147 100644 --- a/thunderbird-development/codebase-overview/chat/message-styles.md +++ b/thunderbird-development/codebase-overview/chat/message-styles.md @@ -2,7 +2,7 @@ [Chat Core](./) uses a message style system based on HTML, JS and CSS that is very similar to the one created for [Adium](https://adium.im/). If you plan to create a message style, reading the Adium documentation on the topic may be helpful -- see this [tutorial](https://web.archive.org/web/20160408094746/https://trac.adium.im/wiki/CreatingMessageStyles/Tutorial) and this [reference sheet](https://web.archive.org/web/20160715205801/https://trac.adium.im/wiki/CreatingMessageStyles). -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](https://searchfox.org/comm-central/source/mail/components/im/messages) +On the other hand, you may prefer to jump right in, using the default message styles as examples: [https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/components/im/messages](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/components/im/messages) The rest of this page includes a variety of information about the specifics for creating a message theme for Thunderbird. diff --git a/thunderbird-development/codebase-overview/chat/notifications.md b/thunderbird-development/codebase-overview/chat/notifications.md index d50e75a4..0e1667c2 100644 --- a/thunderbird-development/codebase-overview/chat/notifications.md +++ b/thunderbird-development/codebase-overview/chat/notifications.md @@ -10,60 +10,60 @@ _Draft: This page is not complete._ | Topic | Subject | Data | Added | Comment | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| account-added | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | <1.0 | a new account has been created | -| account-connected | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | <1.0 | the account has connected | -| account-connecting | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | <1.0 | the account has started a connection attempt | -| account-connect-error | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | <1.0 | the account has disconnecting with an error | -| account-connect-progress | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | <1.0 | the account is attempting to connect | -| account-disconnected | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | <1.0 | the account has disconnected | -| account-disconnecting | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | <1.0 | the account is disconnecting without an error reason | -| account-list-updated | [imIAccountsService](https://searchfox.org/comm-central/source/chat/components/public/imIAccountsService.idl) | null | <1.0 | the list of accounts has been updated | -| account-removed | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | <1.0 | an account is about to be removed | -| account-updated | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | <1.0 | | -| app-handler-pane-loaded | [nsIDOMWindow](https://searchfox.org/comm-central/source/mozilla/dom/interfaces/base/nsIDOMWindow.idl) | null | <1.0 | Applications pane in preferences window is loaded | -| autologin-processed | [imICoreService](https://searchfox.org/comm-central/source/chat/components/public/imICoreService.idl) | null | <1.0 | imICoreService::processAutoLogin() is complete | -| browser-request | [prplIRequestBrowser](https://searchfox.org/comm-central/source/chat/components/public/prplIRequest.idl) | null | <1.0 | Used by protocol plugins to bring up a browser window (e.g. for an OAuth request) | -| closing-conversation | [prplIConversation](https://searchfox.org/comm-central/source/chat/components/public/prplIConversation.idl) | null | <1.0 | | -| contact-moved |

imIContactsService
imIContact

| null | <1.0 | when a contact has been moved (removed from one tag, added to another, or both) | +| account-added | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | <1.0 | a new account has been created | +| account-connected | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | <1.0 | the account has connected | +| account-connecting | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | <1.0 | the account has started a connection attempt | +| account-connect-error | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | <1.0 | the account has disconnecting with an error | +| account-connect-progress | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | <1.0 | the account is attempting to connect | +| account-disconnected | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | <1.0 | the account has disconnected | +| account-disconnecting | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | <1.0 | the account is disconnecting without an error reason | +| account-list-updated | [imIAccountsService](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccountsService.idl) | null | <1.0 | the list of accounts has been updated | +| account-removed | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | <1.0 | an account is about to be removed | +| account-updated | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | <1.0 | | +| app-handler-pane-loaded | [nsIDOMWindow](https://github.com/thunderbird/thunderbird-desktop/blob/main/mozilla/dom/interfaces/base/nsIDOMWindow.idl) | null | <1.0 | Applications pane in preferences window is loaded | +| autologin-processed | [imICoreService](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imICoreService.idl) | null | <1.0 | imICoreService::processAutoLogin() is complete | +| browser-request | [prplIRequestBrowser](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIRequest.idl) | null | <1.0 | Used by protocol plugins to bring up a browser window (e.g. for an OAuth request) | +| closing-conversation | [prplIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIConversation.idl) | null | <1.0 | | +| contact-moved |

imIContactsService
imIContact

| null | <1.0 | when a contact has been moved (removed from one tag, added to another, or both) | | contact-tag-added | imIContact | tag.id | <1.0 | when a tag is added to a contact | | contact-tag-removed | imIContact | tag.id | <1.0 | when a tag is removed from a contact | -| conversation-closed | [prplIConversation](https://searchfox.org/comm-central/source/chat/components/public/prplIConversation.idl) | null | <1.0 | conversation going away | -| conversation-left-chat | [prplIConversation](https://searchfox.org/comm-central/source/chat/components/public/prplIConversation.idl) | null | <1.0 | the user has left the conversation (but it might remain visible) | -| conversation-loaded | [nsISupports](https://searchfox.org/comm-central/source/mozilla/xpcom/base/nsISupports.idl) | null or details | <1.0 | subject is a \, if fired because an existing conversation is moved from one window to another, the data parameter ("details") will contain the string "imported". | -| im-sent | [prplIConversation](https://searchfox.org/comm-central/source/chat/components/public/prplIConversation.idl) | message text | <1.0 | on sending an IM (whether or not it succeeded) | -| new-conversation | [prplIConversation](https://searchfox.org/comm-central/source/chat/components/public/prplIConversation.idl) | null | <1.0 | conversation created | -| new-ui-conversation | [imIConversation](https://searchfox.org/comm-central/source/chat/components/public/imIConversationsService.idl) | null | <1.0 | | -| prpl-quit | [imICoreService](https://searchfox.org/comm-central/source/chat/components/public/imICoreService.idl) | null | 1.2 | Core shutdown, was previously purple-quit | -| status-changed | [imICoreService](https://searchfox.org/comm-central/source/chat/components/public/imICoreService.idl) | status text | <1.0 | user (not buddy) status change | -| tag-hidden | [imITag](https://searchfox.org/comm-central/source/chat/components/public/imITagsService.idl) | null | <1.0 | fired when a tag is hidden | -| tag-shown | [imITag](https://searchfox.org/comm-central/source/chat/components/public/imITagsService.idl) | null | <1.0 | fired when a tag is set to be shown (unhiding it) | +| conversation-closed | [prplIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIConversation.idl) | null | <1.0 | conversation going away | +| conversation-left-chat | [prplIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIConversation.idl) | null | <1.0 | the user has left the conversation (but it might remain visible) | +| conversation-loaded | [nsISupports](https://github.com/thunderbird/thunderbird-desktop/blob/main/mozilla/xpcom/base/nsISupports.idl) | null or details | <1.0 | subject is a \, if fired because an existing conversation is moved from one window to another, the data parameter ("details") will contain the string "imported". | +| im-sent | [prplIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIConversation.idl) | message text | <1.0 | on sending an IM (whether or not it succeeded) | +| new-conversation | [prplIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIConversation.idl) | null | <1.0 | conversation created | +| new-ui-conversation | [imIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIConversationsService.idl) | null | <1.0 | | +| prpl-quit | [imICoreService](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imICoreService.idl) | null | 1.2 | Core shutdown, was previously purple-quit | +| status-changed | [imICoreService](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imICoreService.idl) | status text | <1.0 | user (not buddy) status change | +| tag-hidden | [imITag](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imITagsService.idl) | null | <1.0 | fired when a tag is hidden | +| tag-shown | [imITag](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imITagsService.idl) | null | <1.0 | fired when a tag is set to be shown (unhiding it) | | ui-conversation-closed | | null | <1.0 | | | unread-im-count-changed | | count of unread messages | <1.0 | fired when the number of unread messages changes | -| new-text | [imIMessage](https://searchfox.org/comm-central/source/chat/components/public/imIConversationsService.idl) | null | 1.5 | New message is about to be displayed. | -| new-directed-incoming-message | [imIMessage](https://searchfox.org/comm-central/source/chat/components/public/imIConversationsService.idl) | null | 1.5 | New incoming message that is either a direct message or highlights the user. | -| ui-conversation-replaced | [imIConversation](https://searchfox.org/comm-central/source/chat/components/public/imICoreService.idl) | null | 91 | The subject UI conversation is about to be replaced by a new instance (with different interfaces but the same ID). | -| conversation-update-type | [imIConversation](https://searchfox.org/comm-central/source/chat/components/public/imICoreService.idl) | null | 91 | The type of the underlying prplIConversation has changed. Is always preceded by a ui-conversation-replaced notification that disposes of the old UIConversation instance, while this will have the new one as subject. | -| account-sessions-changed | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | 91 | The account session list has changed | -| account-encryption-status-changed | [imIAccount](https://searchfox.org/comm-central/source/chat/components/public/imIAccount.idl) | null | 91 | The account encryption status info has changed | +| new-text | [imIMessage](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIConversationsService.idl) | null | 1.5 | New message is about to be displayed. | +| new-directed-incoming-message | [imIMessage](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIConversationsService.idl) | null | 1.5 | New incoming message that is either a direct message or highlights the user. | +| ui-conversation-replaced | [imIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imICoreService.idl) | null | 91 | The subject UI conversation is about to be replaced by a new instance (with different interfaces but the same ID). | +| conversation-update-type | [imIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imICoreService.idl) | null | 91 | The type of the underlying prplIConversation has changed. Is always preceded by a ui-conversation-replaced notification that disposes of the old UIConversation instance, while this will have the new one as subject. | +| account-sessions-changed | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | 91 | The account session list has changed | +| account-encryption-status-changed | [imIAccount](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIAccount.idl) | null | 91 | The account encryption status info has changed | ### imIBuddy | Topic | Subject | Data | Added | Notes | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----- | ----------------------------------------------------------------------------------- | | account-buddy-availability-changed | [prplIAccountBuddy](https://dxr.mozilla.org/comm-central/source/chat/components/public/imIContactsService.idl) | null | <1.0 | Possibly fired on account buddy status change | -| account-buddy-display-name-changed |

imIContactsService
imIAccountBuddy

| old serverAlias | <1.0 | Fired when setting imIAccountBuddy::serverAlias | +| account-buddy-display-name-changed |

imIContactsService
imIAccountBuddy

| old serverAlias | <1.0 | Fired when setting imIAccountBuddy::serverAlias | | account-buddy-icon-changed | imIAccountBuddy | null | <1.0 | Fired when setting imIAccountBuddy::buddyIconFilename | | account-buddy-signed-off | imIAccountBuddy | null | <1.0 | Possibly fired on account buddy status change | | account-buddy-signed-on | imIAccountBuddy | null | <1.0 | Possibly fired on account buddy status change | | account-buddy-status-changed | imIAccountBuddy | null | <1.0 | Possibly fired on account buddy status change | -| buddy-added | [imIBuddy](https://searchfox.org/comm-central/source/chat/components/public/imIContactsService.idl) | null | <1.0 | In response to account-buddy-added if the buddy previously had no account buddies | -| buddy-availability-changed | [imIBuddy](https://searchfox.org/comm-central/source/chat/components/public/imIContactsService.idl) | null | <1.0 | possibly fired on imIBuddy status updates | -| buddy-display-name-changed | [imIBuddy](https://searchfox.org/comm-central/source/chat/components/public/imIContactsService.idl) | old serverAlias | <1.0 | possibly in response to account-buddy-display-name-changed on the preferred account | -| buddy-preferred-account-changed |

imIContactsService
imIBuddy

| null | <1.0 | when setting imIBuddy::preferredAccountBuddy (internally) | -| buddy-removed | [imIBuddy](https://searchfox.org/comm-central/source/chat/components/public/imIContactsService.idl) | null | <1.0 | In response to account-buddy-removed if the buddy no longer has any account buddies | -| buddy-signed-off | [imIBuddy](https://searchfox.org/comm-central/source/chat/components/public/imIContactsService.idl) | null | <1.0 | possibly fired on imIBuddy status updates | -| buddy-signed-on | [imIBuddy](https://searchfox.org/comm-central/source/chat/components/public/imIContactsService.idl) | null | <1.0 | possibly fired on imIBuddy status updates | -| buddy-status-changed | [imIBuddy](https://searchfox.org/comm-central/source/chat/components/public/imIContactsService.idl) | null | <1.0 | possibly fired on imIBuddy status updates | +| buddy-added | [imIBuddy](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIContactsService.idl) | null | <1.0 | In response to account-buddy-added if the buddy previously had no account buddies | +| buddy-availability-changed | [imIBuddy](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIContactsService.idl) | null | <1.0 | possibly fired on imIBuddy status updates | +| buddy-display-name-changed | [imIBuddy](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIContactsService.idl) | old serverAlias | <1.0 | possibly in response to account-buddy-display-name-changed on the preferred account | +| buddy-preferred-account-changed |

imIContactsService
imIBuddy

| null | <1.0 | when setting imIBuddy::preferredAccountBuddy (internally) | +| buddy-removed | [imIBuddy](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIContactsService.idl) | null | <1.0 | In response to account-buddy-removed if the buddy no longer has any account buddies | +| buddy-signed-off | [imIBuddy](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIContactsService.idl) | null | <1.0 | possibly fired on imIBuddy status updates | +| buddy-signed-on | [imIBuddy](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIContactsService.idl) | null | <1.0 | possibly fired on imIBuddy status updates | +| buddy-status-changed | [imIBuddy](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIContactsService.idl) | null | <1.0 | possibly fired on imIBuddy status updates | ### imIContact @@ -94,35 +94,35 @@ Note: all imIContact notifications also go to any imITag it belongs to, as well | Topic | Subject | Data | Added | Notes | | ---------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| chat-buddy-add | [nsISimpleEnumerator](https://searchfox.org/comm-central/source/mozilla/xpcom/ds/nsISimpleEnumerator.idl) | null | <1.0 | When users join a chat. The enumerator elements are prplIConvChatBuddy. | -| chat-buddy-removed | [nsISimpleEnumerator](https://searchfox.org/comm-central/source/mozilla/xpcom/ds/nsISimpleEnumerator.idl) | null | <1.0 | When chat buddies leave a chat. The enumerator elements are nsISupportsString of the user name. | -| chat-buddy-update | [prplIConvChatBuddy](https://searchfox.org/comm-central/source/chat/components/public/prplIConversation.idl) | old name, if the chat buddy is being renamed | <1.0 | data is null if this is not a rename | +| chat-buddy-add | [nsISimpleEnumerator](https://github.com/thunderbird/thunderbird-desktop/blob/main/mozilla/xpcom/ds/nsISimpleEnumerator.idl) | null | <1.0 | When users join a chat. The enumerator elements are prplIConvChatBuddy. | +| chat-buddy-removed | [nsISimpleEnumerator](https://github.com/thunderbird/thunderbird-desktop/blob/main/mozilla/xpcom/ds/nsISimpleEnumerator.idl) | null | <1.0 | When chat buddies leave a chat. The enumerator elements are nsISupportsString of the user name. | +| chat-buddy-update | [prplIConvChatBuddy](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIConversation.idl) | old name, if the chat buddy is being renamed | <1.0 | data is null if this is not a rename | | chat-buddy-topic | | null | <1.0 | The chat topic was updated | -| new-text | [prplIMessage](https://searchfox.org/comm-central/source/chat/components/public/prplIMessage.idl) | null | <1.0 | A new message will be written to a conversation. This can be an incoming, outgoing or system message. Subject was purpleIMessage until 1.2. | -| update-text | [prplIMessage](https://searchfox.org/comm-central/source/chat/components/public/prplIMessage.idl) | null | 91 | An existing message is updated based on the `remoteId` of the message. | +| new-text | [prplIMessage](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIMessage.idl) | null | <1.0 | A new message will be written to a conversation. This can be an incoming, outgoing or system message. Subject was purpleIMessage until 1.2. | +| update-text | [prplIMessage](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIMessage.idl) | null | 91 | An existing message is updated based on the `remoteId` of the message. | | update-buddy-status | | null | <1.0 | away-ness or online/offline | | update-conv-chatleft | | null | <1.0 | the user has left the chat (it might remain visible) | | update-conv-title | | null | <1.0 | | | update-typing | | null | <1.0 | | -| preparing-message | [imIOutgoingMessage](https://searchfox.org/comm-central/source/chat/components/public/imIConversationsService.idl) | null | 1.5 | Outgoing message before it's been prepared for sending by the protocol | -| sending-message | [imIOutgoingMessage](https://searchfox.org/comm-central/source/chat/components/public/imIConversationsService.idl) | null | 1.5 | Outgoing message was prepared (and potentially split into multiple messages) and will be sent by the protocol after this observer. | +| preparing-message | [imIOutgoingMessage](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIConversationsService.idl) | null | 1.5 | Outgoing message before it's been prepared for sending by the protocol | +| sending-message | [imIOutgoingMessage](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIConversationsService.idl) | null | 1.5 | Outgoing message was prepared (and potentially split into multiple messages) and will be sent by the protocol after this observer. | | chat-update-type | null | null | 91 | Conversation changed between being a chat and a direct message conv (`isChat` toggled). | -| update-conv-icon | [prplIConversation](https://searchfox.org/comm-central/source/chat/components/public/prplIConversation.idl) | null | 91 | The `convIconFilename` of the conversation changed. | -| update-conv-encryption | [prplIConversation](https://searchfox.org/comm-central/source/chat/components/public/prplIConversation.idl) | null | 91 | The `encryptionState` of the conversation changed. | +| update-conv-icon | [prplIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIConversation.idl) | null | 91 | The `convIconFilename` of the conversation changed. | +| update-conv-encryption | [prplIConversation](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/prplIConversation.idl) | null | 91 | The `encryptionState` of the conversation changed. | ### imIConversation | Topic | Subject | Data | Added | Notes | | ----------------------------- | ---------------------------------------------------------------------------------------------------------- | ---- | ----- | ------------------------------------------------------------------------------------------------ | -| received-message | [imIMessage](https://searchfox.org/comm-central/source/chat/components/public/imIConversationsService.idl) | null | 1.5 | New message is about to be prepared for display. | -| new-text | [imIMessage](https://searchfox.org/comm-central/source/chat/components/public/imIConversationsService.idl) | null | 1.5 | New message is about to be displayed. (Before 1.5 probably just passed along the `prplIMessage`) | -| new-directed-incoming-message | [imIMessage](https://searchfox.org/comm-central/source/chat/components/public/imIConversationsService.idl) | null | 1.5 | New incoming message that is either a direct message or highlights the user. | +| received-message | [imIMessage](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIConversationsService.idl) | null | 1.5 | New message is about to be prepared for display. | +| new-text | [imIMessage](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIConversationsService.idl) | null | 1.5 | New message is about to be displayed. (Before 1.5 probably just passed along the `prplIMessage`) | +| new-directed-incoming-message | [imIMessage](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIConversationsService.idl) | null | 1.5 | New incoming message that is either a direct message or highlights the user. | ### imIUserStatusInfo | Topic | Subject | Data | Added | Notes | | ------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------- | ----- | ----- | -| status-changed | [imIUserStatusInfo](https://searchfox.org/comm-central/source/chat/components/public/imIUserStatusInfo.idl) | Status Text (string) | ? | | -| user-icon-changed | [imIUserStatusInfo](https://searchfox.org/comm-central/source/chat/components/public/imIUserStatusInfo.idl) | New icon file name (string) | ? | | -| user-display-name-changed | [imIUserStatusInfo](https://searchfox.org/comm-central/source/chat/components/public/imIUserStatusInfo.idl) | New display name (string) | ? | | -| idle-time-changed | [imIUserStatusInfo](https://searchfox.org/comm-central/source/chat/components/public/imIUserStatusInfo.idl) | New idle time (number) | ? | | +| status-changed | [imIUserStatusInfo](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIUserStatusInfo.idl) | Status Text (string) | ? | | +| user-icon-changed | [imIUserStatusInfo](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIUserStatusInfo.idl) | New icon file name (string) | ? | | +| user-display-name-changed | [imIUserStatusInfo](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIUserStatusInfo.idl) | New display name (string) | ? | | +| idle-time-changed | [imIUserStatusInfo](https://github.com/thunderbird/thunderbird-desktop/blob/main/chat/components/public/imIUserStatusInfo.idl) | New idle time (number) | ? | | diff --git a/thunderbird-development/codebase-overview/mail-front-end.md b/thunderbird-development/codebase-overview/mail-front-end.md index 403d30c5..99cf3f7b 100644 --- a/thunderbird-development/codebase-overview/mail-front-end.md +++ b/thunderbird-development/codebase-overview/mail-front-end.md @@ -8,7 +8,7 @@ In January 2023 the mail front-end was rebuilt from scratch, replacing what evol ## 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](https://searchfox.org/comm-central/source/mail/base/content/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. +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](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/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: @@ -33,7 +33,7 @@ The standalone mail window also contains a XUL `` displaying `about:mes ## 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](https://searchfox.org/comm-central/source/mail/base/content/about3Pane.xhtml) and similarly named [JS](https://searchfox.org/comm-central/source/mail/base/content/about3Pane.js), [CSS](https://searchfox.org/comm-central/source/mail/themes/shared/mail/about3Pane.css) and [Fluent](https://searchfox.org/comm-central/source/mail/locales/en-US/messenger/about3Pane.ftl) files. +`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](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/about3Pane.xhtml) and similarly named [JS](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/about3Pane.js), [CSS](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/themes/shared/mail/about3Pane.css) and [Fluent](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/locales/en-US/messenger/about3Pane.ftl) files. ### Folder pane @@ -59,6 +59,6 @@ If an account is selected in the folder pane instead of a folder, yet another `< ## 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](https://searchfox.org/comm-central/source/mail/base/content/aboutMessage.xhtml), [aboutMessage.js](https://searchfox.org/comm-central/source/mail/base/content/aboutMessage.js), [messageHeader.css](https://searchfox.org/comm-central/source/mail/themes/shared/mail/messageHeader.css) and [about3Pane.ftl](https://searchfox.org/comm-central/source/mail/locales/en-US/messenger/about3Pane.ftl) files. +`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](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/aboutMessage.xhtml), [aboutMessage.js](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/base/content/aboutMessage.js), [messageHeader.css](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/themes/shared/mail/messageHeader.css) and [about3Pane.ftl](https://github.com/thunderbird/thunderbird-desktop/blob/main/mail/locales/en-US/messenger/about3Pane.ftl) files. Message contents themselves are displayed in a `` (if you're counting, we're now three deep) which can be accessed by the `content` property of an `about:message` `window`. diff --git a/thunderbird-development/fixing-a-bug/README.md b/thunderbird-development/fixing-a-bug/README.md index 557c6b4c..b962cf16 100644 --- a/thunderbird-development/fixing-a-bug/README.md +++ b/thunderbird-development/fixing-a-bug/README.md @@ -16,7 +16,7 @@ Use the [Advanced Search](https://bugzilla.mozilla.org/query.cgi?format=advanced ## Search for Code References -Making sense of the **Thunderbird** source code, and knowing where to look, will take some time. The code base is pretty big and if you never worked with `XBL` or `Custom Elements` it can be overwhelming at first. We recommend using our code search engine, [SearchFox](https://searchfox.org/comm-central/source/), to inspect the source code and find snippets and references to help you out while investigating a bug. +Making sense of the **Thunderbird** source code, and knowing where to look, will take some time. The code base is pretty big and if you never worked with `XBL` or `Custom Elements` it can be overwhelming at first. We recommend using our code search engine, [SearchFox](https://searchfox.org/comm-central/source/), or the [GitHub Source](https://github.com/thunderbird/thunderbird-desktop) to inspect the source code and find snippets and references to help you out while investigating a bug. ## Debugging Core Code @@ -24,23 +24,54 @@ JavaScript code can be debugged using the built-in [developer tools toolbox](htt ## Creating Patches -### Configuring Mercurial +### Checkout the Source Code -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). +If you don't need to build Thunderbird, you can just get the Thunderbird source: ``` -[ui] -username = Your Name +git clone https://github.com/thunderbird/thunderbird-desktop +``` + +If you plan to build with your changes, you'll first need to get the latest Firefox source code, and check it out into a local directory `source` (or however you want to call it). Then, get the latest Thunderbird source code. It needs to be placed **inside** the Mozilla source code, in a directory named `comm/`: + +``` +git clone https://github.com/mozilla-firefox/firefox source/ +cd source/ +git clone https://github.com/thunderbird/thunderbird-desktop comm/ +``` + +### Configuring Git + +To ensure your work is correctly attributed to you, and to make the reviewer's task easier, these options should be set in your Git configuration. -[diff] -git = 1 -showfunc = 1 -unified = 8 ``` +git config --global user.name "Your Full Name" +git config --global user.email "you@example.com" +``` + +### Committing a Patch -### Mercurial Workflows +Make the changes you need in the codebase. + +{% hint style="note" %} +If you are unsure of what changes you need to make, or need help from the mentor of the bug, please don’t hesitate to use the needinfo feature (“Request information from”) on Bugzilla to get the attention of your mentor. +{% endhint %} -Mercurial is pretty flexible in terms of allowing writing your own code and keeping it separate from the main code base. See [the page on using Mercurial bookmarks](using-mercurial-bookmarks.md) for more information. +After making your changes, visualize your changes to ensure you’re including all the necessary work: + +``` +# For files changed/added/removed +$ git status + +# For detailed line changes +$ git diff +``` + +Then commit your changes: + +``` +$ git commit +``` ## Commit messages @@ -55,7 +86,6 @@ Optionally, a longer description of the change. This can span multiple lines. ``` - For follow-up commits that fix a problem with a lint test or other failure, the suggested form is: ```text @@ -70,14 +100,30 @@ Bug NNNN - Port bug ZZZZ: Useful short description. r?reviewer 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. Thunderbird code is divided into modules, each with an owner and peers. Generally, these are the best people to review your changes. Here's [the list of module owners and peers for Thunderbird](https://wiki.mozilla.org/Modules/Thunderbird). [Calendar](https://wiki.mozilla.org/Modules/Calendar) and [MailNews Core](https://wiki.mozilla.org/Modules/MailNews\_Core) modules have separate lists. -Scanning through the recent commits in mercurial should also give you an idea of who is active in various areas of the code. Failing that you can always [ask around](https://developer.thunderbird.net/add-ons/community). +You can also run git log ` on the relevant files, and look who usually is reviewing the actual changes (ie. not reformat, renaming of variables, etc). + +## Reviewing before submitting + +To review your commit, run: + +``` +$ git log +``` + +To review your patch, run: +``` +$ git show +``` + +## Working with a stack of patches + +[More information on how to work with stack of patches](https://firefox-source-docs.mozilla.org/contributing/stack_quickref.html#working-with-stack-of-patches-quick-reference) ## Submitting a Patch @@ -87,13 +133,19 @@ There is a command line tool, `moz-phab`, which makes it easy to submit local ch See the [moz-phab setup and installation](https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html#setting-up-mozphab) docs. -With `moz-phab` you can submit local mercurial changeset(s) like this: +Once you want to submit your patches (make sure you use the right commit message), run: ``` -$ moz-phab submit [start_changeset] [end_changeset] +$ moz-phab ``` -The start/end changesets are optional. If omitted, `moz-phab` will guess which one(s) you mean. +It will publish all the currently applied patches to Phabricator and inform the reviewer. + +If you wrote several patches on top of each other, run: + +``` +$ moz-phab submit :: +``` It'll ask for confirmation before uploading, so don't worry too much about accidental submissions. @@ -101,18 +153,49 @@ It'll ask for confirmation before uploading, so don't worry too much about accid You can find more details in the `moz-phab` [README](https://github.com/mozilla-conduit/review/blob/master/README.md#submitting-commits-to-phabricator). -## Updating patches +## Updating a submitted patch + +It is rare that a reviewer will accept the first version of patch. Moreover, as the code review bot might suggest some improvements, changes to your patch may be required. + +If your patch is not loaded in your working directory, you first need to re-apply it: -It's very common for patches to require some updates before being accepted. Locally, you can use `hg commit --amend` to update a changeset. +``` +$ moz-phab patch D + +# Or you can use the URL of the revision on Phabricator +$ moz-phab patch https://phabricator.services.mozilla.com/D +``` -Phabricator tracks uploaded patches by adding a line to the commit message: +Make your changes in the working folder and run: ``` -Differential Revision: +$ git commit --amend ``` -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. +After amending the patch, you will need to submit it using moz-phab again. {% hint style="warning" %} -If you're juggling and merging local changesets with `hg histedit`, make sure you preserve the `Differential Revision:` line in the commit message for any patches you're planning to resubmit! +Don’t use `git commit --amend -m`. + +Phabricator tracks revision by editing the commit message when a revision is created to add a special `Differential Revision: ` line. + +When `--amend -m` is used, that line will be lost, leading to the creation of a new revision when re-submitted, which isn’t the desired outcome. {% endhint %} + +If you wrote many changes, you can squash or edit commits with the command: + +``` +$ git rebase -i +``` + +The submission step is the same as for the initial patch. + +[More information on how to work with stack of patches](https://firefox-source-docs.mozilla.org/contributing/stack_quickref.html#working-with-stack-of-patches-quick-reference) + +## Update the working directory + +If you’re finished with a patch and would like to return to the tip to make a new patch: + +``` +$ git pull --rebase +``` diff --git a/thunderbird-development/fixing-a-bug/care-and-feeding-of-the-tree.md b/thunderbird-development/fixing-a-bug/care-and-feeding-of-the-tree.md index e29ccae0..01c43924 100644 --- a/thunderbird-development/fixing-a-bug/care-and-feeding-of-the-tree.md +++ b/thunderbird-development/fixing-a-bug/care-and-feeding-of-the-tree.md @@ -2,13 +2,17 @@ ## Landing "checkin-needed" patches -Patches can land on comm-central at any time, but in general we try to organise this around when mozilla-central changes. Since the mozilla-central code can break Thunderbird in any number of ways, and they won't stop to wait for us to catch up, we try to meet every mozilla-central push with a push of our own. +Patches can land on Thunderbird's main branch at any time, but in general we try to organise this around when Firefox main changes. Since the Firefox code can break Thunderbird in any number of ways, and they won't stop to wait for us to catch up, we try to meet every Firefox push to main with a push of our own. -Sheriffs aim to merge changes to mozilla-central at (very roughly) 0400, 1000, 1600 and 2200 UTC. After a merge, something should land on comm-central to start a new build. Land something of your own or check for bugs flagged [checkin-needed](https://bugzilla.mozilla.org/buglist.cgi?keywords=checkin-needed-tb). +{% hint style="info" %} +Firefox main mirrors to mozilla-central, and Thunderbird main mirrors to comm-central. Continuous Integration is run against mozilla-central and comm-central. +{% endhint %} + +Sheriffs aim to merge changes to Firefox main at (very roughly) 0400, 1000, 1600 and 2200 UTC. After a merge, something should land on Thunderbird main to start a new build. Land something of your own or check for bugs flagged [checkin-needed](https://bugzilla.mozilla.org/buglist.cgi?keywords=checkin-needed-tb). ## Closing or Opening the Tree -In extreme circumstances the tree can to be closed to prevent further pushes. Some members of the Thunderbird team (Daniel, Geoff, Magnus, Rob) have authorisation to do this, or you can request the help of a MoCo sheriff in #sheriffs. +In extreme circumstances the tree can to be closed to prevent further pushes. Some members of the Thunderbird team (Daniel, Geoff, Magnus, Stephen, Corey) have authorisation to do this, or you can request the help of a MoCo sheriff in #sheriffs. ## Existing failures @@ -29,7 +33,7 @@ If a _new_ intermittent failure appears, you can click the blue bug icon next to {% hint style="info" %} Usually new intermittent failures get ignored for a while and they go away, or are so infrequent it's not worth the hassle. Don't feel the need to file a bug about every one you see. -Some things aren't usually starred, like out-of-memory failures on debug builds or failures from mozilla-central tests (ours all start with `comm/`). There's little benefit to doing so. +Some things aren't usually starred, like out-of-memory failures on debug builds or failures from Firefox tests (ours all start with `comm/`). There's little benefit to doing so. {% endhint %} The pinboard can be used for other things. Collect tasks there with the pin icon or ctrl+clicking on them, and you can mark tasks as expected failures or to say they've been fixed by something that has landed since. @@ -52,9 +56,9 @@ This is really not an easy thing to describe. Much of it comes down to intuition Check the Failure Summary of TreeHerder for the most basic details. Check the task log for more information. Mochitests usually produce a screenshot of the first failure in a task. This is linked from the Job Details section named mozilla-test-fail-screenshot\_XxYyZz.png. -#### What changed on mozilla-central? +#### What changed in Firefox? -The most likely cause of an unexpected failure is a change to mozilla-central. Sometimes we are warned in advance of things we need to do, sometimes not. To figure out what has changed on mozilla-central, get the revision from the last build before the problem and the first build with the problem, by clicking on the decision task (D or Nd) and looking at the Artifacts tab: +The most likely cause of an unexpected failure is a change to Firefox. Sometimes we are warned in advance of things we need to do, sometimes not. To figure out what has changed in Firefox main, get the revision from the last build of mozilla-central before the problem and the first build with the problem, by clicking on the decision task (D or Nd) and looking at the Artifacts tab: ![](../../.gitbook/assets/bitmap.png) @@ -83,19 +87,19 @@ To disable a test, add the appropriate `skip-if` notation to the test manifest. If it looks like a Thunderbird developer is responsible for causing a problem, contact them or their reviewer. If neither can be found and there's a serious failure, consider backing out their changes. Check whether you're right first – finding out your work has been backed out overnight is not the nicest way to start a day. -When performing a backout, use the `hg oops` command (part of the `mozext` extension from [Mozilla’s Version Control Tools](https://mozilla-version-control-tools.readthedocs.io)). The extension needs to be enabled in your `.hgrc` file as described in [Landing A Patch](landing-a-patch.md). +When performing a backout, use the `git revert` command. -For backing out a single revision, use `hg oops -er `. This will open an editor with a commit message started. Add a reason for the backout like: +For backing out a single revision, use `git revert `. This will open an editor with a commit message started. Update the commit message as follows: ``` Backed out changeset def0af88e262 (bug 1359017) for mochitest failures. r=backout ``` -For multiple revisions, `hg oops` can condense the backout to a single commit with the `-s` argument like `hg oops -esr 2f665a0a379f -r 478cffed4b5f`. +To condense the backout of multiple changes to a single commit, you can use `git revert ^..` for contiguous changes, or `git revert ` for non-contiguous changes. After pushing the backout, update the bug in Bugzilla: * Mention the reason for the backout. -* Link to the backout commit starting with https://hg.mozilla.org +* Link to the backout commit starting with https://github.com/thunderbird/thunderbird-desktop * Link to the push in Treeherder * Set the NEEDINFO flag in Bugzilla to make sure the patch author sees it. diff --git a/thunderbird-development/fixing-a-bug/using-mercurial-bookmarks.md b/thunderbird-development/fixing-a-bug/using-mercurial-bookmarks.md deleted file mode 100644 index 6d5f7e2b..00000000 --- a/thunderbird-development/fixing-a-bug/using-mercurial-bookmarks.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -description: Tutorial on how to use Mercurial bookmarks. ---- - -# Using Mercurial Bookmarks - -This is a brief "quick start" guide to using Mercurial Bookmarks for Thunderbird development. For more in-depth documentation see the [Using Bookmarks](https://mozilla-version-control-tools.readthedocs.io/en/latest/hgmozilla/bookmarks.html) section of Mercurial for Mozillians and the [Bookmarks](https://www.mercurial-scm.org/wiki/Bookmarks) page on the Mercurial Wiki. - -{% hint style="info" %} -If you have used git, it will help to know that bookmarks in Mercurial are very similar to _branches_ in git and involve similar workflows. (Note that Mercurial's _branches_ are very different from git branches.) You may find it helpful learn more about the similarities and differences between Mercurial and Git. For example, see the in-depth discussion in [Mercurial for Git Users (and vice versa)](https://www.rath.org/mercurial-for-git-users-and-vice-versa.html). -{% endhint %} - -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 - - [TortoiseHG](https://tortoisehg.bitbucket.io/) - - 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`. diff --git a/thunderbird-development/fixing-a-bug/using-mercurial-queues.md b/thunderbird-development/fixing-a-bug/using-mercurial-queues.md deleted file mode 100644 index 14200f74..00000000 --- a/thunderbird-development/fixing-a-bug/using-mercurial-queues.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -description: Tutorial on how to activate and use Mercurial Queues. ---- - -# Using Mercurial Queues - -{% hint style="danger" %} -Mercurial Queues is not compatible with the `moz-phab` code submission tool. This page is here for historical reference only. -{% endhint %} - -{% hint style="info" %} -If you're already familiar with Mercurial Queues but you need a quick overview of all the available commands, take a look at the [Mercurial Queues reference](http://hgbook.red-bean.com/read/mercurial-queues-reference.html) -{% endhint %} - -## 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. - -For instance, unless you're running the [mqext](https://bitbucket.org/sfink/mqext/), `hg qrefresh` is destructive. It replaces your previous version of the current patch with what's in your working directory. The previous version is lost. - -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. -* Version your patch queue to save changes. The [mqext](https://bitbucket.org/sfink/mqext/) extension can make this much easier. - -## 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: - -```bash -[extensions] -mq = -``` - -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. - -{% hint style="info" %} -The commit message is optional and you can add it at a later time with a `qrefresh`. -{% endhint %} - -## 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. - -{% hint style="info" %} -Merge conflicts can happen when reapplying your patches after pulling updates from upstream. Simply fix the merging issues and `qrefresh` your patches. -{% endhint %} - -## 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: - -```bash -hg qpop -a # Unapply all patches -hg qpush --move patch-name # Apply only one patch, reordering as needed -``` - -With older Mercurial versions, you can do this: - -```bash -hg qpop -a # Unapply all patches -$EDITOR .hg/patches/series # Manually rearrange the lines of the series file -hg qpush patch-name # Reapply patches -- watch out for rejects! -``` - -{% hint style="warning" %} -Reordering patches that touch the same file can cause conflicts when you push! If this happens, `hg qpush` will tell you, and it will leave `.rej` files in your working directory. To avoid losing work, you must manually apply these rejected changes, then `hg qrefresh`. -{% endhint %} - -## 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. - -```bash -hg qimport https://bugzilla.mozilla.org/attachment.cgi?id=9086264 -n patch-name -hg qimport ~/Your/Chosen/Directory/filename.patch -n patch-name -hg qimport https://hg.mozilla.org/comm-central/rev/0e7bfdf1b900 -``` - -If you have the `qimportbz` extension installed, you can also import by specifying a bug number: - -```bash -hg qimport bz:1574724 -``` - -### Workflow Overview - -Here's a quick overview of a standard workflow you will be using with MQ. - -```bash -hg qnew bug-123456-fix -... change some files ... -hg qrefresh -... change some more files ... -hg qrefresh -m "Bug 123456: A brief summary of the changes you have made." -``` - -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: - -```bash -hg qbackout -r 0e7bfdf1b900 -hg qbackout -r 0e7bfdf1b900:0e7bfdf1b901 (multiple consecutive changesets) -hg qbackout -r 0e7bfdf1b900 -r 0e7bfdf1b955 (non-consecutive) -hg qbackout -s -r 0e7bfdf1b900:0e7bfdf1b901 (merge into a single backout changeset) -``` - -There is also limited integration with Phabricator with `hg phabread`. That needs a special setup. Ask the resident Thunderbird sheriff for details or read [here](https://www.mercurial-scm.org/wiki/Phabricator#Setting\_up\_hg) (but there's more to it). diff --git a/thunderbird-development/setting-up-a-build-environment.md b/thunderbird-development/setting-up-a-build-environment.md index a488b4a9..29eda2e8 100644 --- a/thunderbird-development/setting-up-a-build-environment.md +++ b/thunderbird-development/setting-up-a-build-environment.md @@ -15,21 +15,48 @@ Before you can build Thunderbird, please follow your platform's build prerequisi ## General Information -### Mercurial Version Control +### Git Version Control -Mozilla uses the [Mercurial version control](https://www.mercurial-scm.org/) 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. +Mozilla uses the [Git version control](https://git-scm.com) 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](https://www.mercurial-scm.org/wiki/Download). +Information for how to install Git is available [via the download page on their wiki](https://git-scm.com/install). -### Mozilla Code Base +### Source Code -#### mozilla-central vs. comm-central +#### Firefox and Thunderbird -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/`. +The latest Firefox and Thunderbird source code is available from the main branches of the [firefox](https://github.com/mozilla-firefox/firefox) and [thunderbird-desktop](https://github.com/thunderbird/thunderbird-desktop) Git repositories, respectively. -Mozilla-central will build Firefox without the comm-central repo present and a few options set (detailed on the [Building Thunderbird](building-thunderbird/) page). +When building locally: +* The root of the Firefox source is often renamed to `source/` but it can be named anything you like. +* The root of the Thunderbird source needs to be placed **inside** the Firefox source code, in a directory that must be named `comm/`. -### Additional Documentation +More detailed can be found on the [Building Thunderbird](building-thunderbird/) page. + +#### Git and Mercurial + +All Firefox and Thunderbird source code development today is performed with Git. However, Mercurial is still used behind the scenes for Continuous Integration. + +Prior to moving to Git, the source code for Firefox and Thunderbird used Mercurial for version control. The Firefox and Thunderbird source code that now lives in the `main` Git branches was historically stored in repositories named mozilla-central and comm-central. + +The following table shows the mapping of git branches to mercurial repositories. Note that all of the git branches exist in the [firefox](https://github.com/mozilla-firefox/firefox) and [thunderbird-desktop](https://github.com/thunderbird/thunderbird-desktop) repositories. + +| Git Branch | Mercurial Repository | +|------------|----------------------| +| main | mozilla-central | +| beta | mozilla-beta | +| release | mozilla-release | +| esr140 | mozilla-esr140 | +| main | comm-central | +| beta | comm-beta | +| release | comm-release | +| esr140 | comm-esr140 | + +For the time being, all Continuous Integration is run against Mercurial, until that tooling can be migrated to Git branches. You'll notice this on [Treeherder](https://treeherder.mozilla.org/jobs?repo=comm-central). + +When code lands in the Firefox and Thunderbird Git repositories, it is mirrored to the corresponding Mercurial repository in order to run CI against it. + +### 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: diff --git a/thunderbird-development/testing/writing-mochitest-tests.md b/thunderbird-development/testing/writing-mochitest-tests.md index 4fe5d66c..5aa3a911 100644 --- a/thunderbird-development/testing/writing-mochitest-tests.md +++ b/thunderbird-development/testing/writing-mochitest-tests.md @@ -20,9 +20,9 @@ add_task(async () => { Many essential functions live in these files. -* [EventUtils](https://searchfox.org/mozilla-central/source/testing/mochitest/tests/SimpleTest/EventUtils.js) -* [BrowserTestUtils](https://searchfox.org/mozilla-central/source/testing/mochitest/BrowserTestUtils/BrowserTestUtils.sys.mjs) -* [MailTestUtils](https://searchfox.org/comm-central/source/mailnews/test/resources/MailTestUtils.sys.mjs) +* [EventUtils](https://github.com/mozilla-firefox/firefox/blob/main/testing/mochitest/tests/SimpleTest/EventUtils.js) +* [BrowserTestUtils](https://github.com/mozilla-firefox/firefox/blob/main/testing/mochitest/BrowserTestUtils/BrowserTestUtils.sys.mjs) +* [MailTestUtils](https://github.com/thunderbird/thunderbird-desktop/blob/main/mailnews/test/resources/MailTestUtils.sys.mjs) `EventUtils` and `BrowserTestUtils` do not need to be imported as they are already available in Mochitest files. `mailTestUtils` requires importing: diff --git a/thunderbird-development/tutorials-and-examples/hello-world.md b/thunderbird-development/tutorials-and-examples/hello-world.md index a55fa00b..4428d7ca 100644 --- a/thunderbird-development/tutorials-and-examples/hello-world.md +++ b/thunderbird-development/tutorials-and-examples/hello-world.md @@ -102,5 +102,5 @@ Spend some time playing around with the menu and even try experimenting with the 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 +git reset --hard ```