Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• BUILDING.md
• README.md
• doc/building.md
• doc/design.md
• doc/testing.md
• package.json
• tools/tsdown_config.ts
• src/test/startup.test.ts

This guide provides instructions for developers who wish to contribute to the Ghostbird project. Ghostbird is a Thunderbird add-on that enables users to compose emails in their favorite text editor using the GhostText protocol.

Contributions are welcome in the form of issue reports and pull requests. By contributing, you agree that your contributions will be dual-licensed under MPL-2.0 OR GPL-3.0-or-later. For general guidelines on open-source contributions, refer to the Open source etiquette.

Sources: CONTRIBUTING.md:1-10, README.md:10-12

Prerequisites

Before you begin, ensure you have the following tools installed on your system.

Tool	Description
Git	For version control.
Thunderbird	The target application for the add-on.
Node.js	LTS version is recommended.
Yarn	Package manager, installed via corepack.
Code Editor	Your preferred editor (e.g., VSCodium, Vim).

Running yarn after setup will fetch the remaining JavaScript development tools.

Sources: CONTRIBUTING.md:16-22

Development Workflow

The typical workflow for making code changes involves forking the repository, making changes, and submitting a pull request. For documentation-only changes, you can edit files directly on the GitHub website.

Sources: CONTRIBUTING.md:28-31

The following diagram illustrates the coding workflow:

Step-by-step Guide

1. Fork and Clone: Fork the repository on GitHub, then clone your fork locally.
2. Install Yarn: Use corepack to install and enable Yarn.

   corepack install && corepack enable
   

3. Install Dependencies: Run yarn in the project root to install all necessary packages.
4. Initial Test: Run yarn test to ensure the project is in a good state before you start.
5. Make Changes: Implement your feature or bug fix.
   • Use yarn build to build the extension.
   • Use yarn watch to automatically rebuild on file changes.
   • Use yarn start to launch Thunderbird with the extension temporarily loaded for debugging.
6. Lint and Format: Ensure your code adheres to the project's style guidelines.
   • yarn check: Checks code style and types.
   • yarn fix: Automatically fixes linting issues.
   • yarn format: Formats the code.
7. Test Again: Run yarn test to make sure your changes haven't introduced any regressions.
8. Commit and Push: Commit your changes with a descriptive message and push them to your fork.
9. Pull Request: Open a pull request against the main branch of the original repository.

Sources: CONTRIBUTING.md:33-83, package.json:23-55

Commit Messages

Follow this template for commit messages to ensure clarity and consistency:

{fix|feat|feat!|docs|refactor|test|chore}: ${what_I_changed_in_imperative_mood}

${you_should_merge_my_awesome_commit_heres_why}
${this_change_impacts_users_like_this}
${this_change_can_be_tested_by_doing_these_steps}

Sources: CONTRIBUTING.md:94-104

Project Structure

The codebase is organized following the Ports and Adapters architecture to promote modularity and testability. This design isolates the core application logic from external dependencies like the Thunderbird API.

Sources: doc/design.md:120-123

Key Directories

Directory	Description
src/root/	Entry points for the extension scripts (background.ts, compose.ts, options.ts).
src/app-*	Infrastructure for handling Thunderbird events in different contexts.
src/ghosttext-session/	Core module implementing the GhostText protocol logic. It has no other project dependencies.
src/ghosttext-runner/	Facilitates interaction between ghosttext-session and the rest of the application.
src/ghosttext-adaptor/	Helper modules for ghosttext-runner.
src/thunderbird/	Wrappers for the Thunderbird MailExtension API.
src/util/	General utility modules.
src/test/	Test code, including sanity checks and dependency analysis.

Sources: doc/design.md:131-150, src/test/startup.test.ts

Module Dependencies

The following diagram shows the dependency flow between the main modules. Arrows point from the dependent to the dependency.

Build System

The project uses tsdown as its bundler, configured via tools/tsdown_config.ts. The build process compiles TypeScript, generates the manifest.json and locale files, copies static assets, and creates the final .xpi package.

Sources: doc/building.md:3-6, tools/tsdown_config.ts:3-17

The build process can be visualized as follows:

This diagram shows how source files are processed by tsdown and its plugins to produce the bundled extension files, which are then packaged into an .xpi file by web-ext.
Sources: doc/building.md:10-33

Build Scripts

The package.json file defines several scripts for common development tasks.

Script	Description
yarn build	Runs checks, tests, and builds the .xpi file.
yarn build-js	Runs tsdown to bundle JavaScript and other assets into dist/ext/.
yarn build-xpi	Uses web-ext to package the contents of dist/ext/ into an .xpi file.
yarn watch	Watches for file changes and rebuilds automatically.
yarn start	Launches Thunderbird with the add-on loaded for debugging.
yarn test	Runs the full suite of unit tests using Vitest.
yarn check	Runs the type checker (tsc) and Biome linter.
yarn fix	Automatically fixes issues found by the Biome linter.
yarn doc	Generates API documentation using TypeDoc.

Sources: package.json:23-55, CONTRIBUTING.md:63-83

Testing

The project uses Vitest for unit testing.

• Running Tests: Use yarn test to run all tests. For a better development experience, yarn test:watch runs tests on file changes, and yarn test:ui provides a graphical interface.
• Test Files: Tests are located in src/test/*.ts for integration-style tests and as "in-source tests" within application files for testing private functions.
• Test Policy: The focus is on testing the core logic within src/ghosttext-session/ and src/ghosttext-runner/. 100% code coverage is not a strict goal.
• Manual Testing: Involves running a GhostText server, opening a compose window in Thunderbird, and interacting with the Ghostbird button to ensure correct behavior.

Sources: doc/testing.md:3-23

Code Style

The project uses Biome for code formatting and linting. The configuration is based on Biome's defaults with some project-specific overrides defined in biome.jsonc. Before creating a pull request, always run yarn fix to ensure your code conforms to the project's style.

Sources: CONTRIBUTING.md:106-111