Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
133 lines (96 loc) · 6.42 KB

CONTRIBUTING.md

File metadata and controls

133 lines (96 loc) · 6.42 KB

Contributing

Open in GitHub Codespaces

Introduction

  • Ghostbird is a Thunderbird add-on that allows you to edit email text in your favorite text editor using the GhostText protocol.
  • It works by connecting to a GhostText server (listening on port 4001 by default) via WebSocket and relaying messages between the compose window and the server.
  • You can find a sequence diagram in doc/design.md.

Requirements

You need at least the following:

Running yarn will fetch the rest of JS tools.

* If you don't like GitHub, we have mirrors on Codeberg and GitLab, although it may not be as up-to-date. Try pinging by raising an issue on one of those platforms.

Workflow (If you found a typo or just want to add documentation)

  • If the edit doesn't touch the code, you can skip the build and test steps below.
  • You can just edit the file on the GitHub website and create a PR.

Workflow (If it involves coding)

  • Pick a task from our project board or add your own issue.
    • Pinging maintainers on the issue page or the discussion page is a good practice.
    • Submitting PRs directly to start a discussion is also fine.
  • Fork the repo.
  • Clone your forked repo and cd into it.
  • Install Yarn by corepack install && corepack enable.
  • Run yarn to install dependencies.
  • Run yarn test. If it fails, that's on the maintainers; please open an issue and attach build/test/result.xml.
  • Make your changes and debug.
    • Run yarn build to build the extension.
    • Run yarn start to launch Thunderbird with the extension loaded temporarily.
    • Add unit tests as a byproduct of debugging, or if you feel generous.
    • Run yarn check and yarn fix to lint and format.
  • Run yarn test again.
  • Commit and push your changes.
  • Create a pull request.
  • Install the changed add-on and dogfood your changes in Thunderbird in the meantime. (You're using Thunderbird daily, aren't you?)

Individual tasks

Build

  • Run yarn build to build. A zip file will be created in dist/.
  • Run yarn watch to watch for changes and rebuild automatically while editing.

Read

  • See the Structure section of design.md for how the code is organized.
  • Run yarn doc to generate API documentation.
  • Ask on the issue or discussion pages if documentation is insufficient to figure out how to implement something.

Code

  • Use your favorite code editor.
  • Run yarn check to check code style and types.
  • Run yarn fix to fix issues found with yarn check.
  • Run yarn format to format code.
  • Running yarn sdk $your_editor_name might make it work more smoothly, e.g., Vim, Emacs, or VSCode. See Yarn SDK for details.

Test

  • Run yarn test.
  • Results are output to build/test/.
  • See doc/testing.md for details.
  • Not adding test cases is fine, but please describe how to test the changed part manually in the commit message.

Debug

  • It's convenient to use yarn exec web-ext run to start Thunderbird with Ghostbird loaded temporarily. It's aliased as yarn start.
    • However, by default, it starts Firefox, which is not what we want.
    • Copy .web-ext-config.example.mjs to .web-ext-config.mjs and adjust to your environment.
  • web-ext will start Thunderbird with a blank profile. You may want to use --keep-profile-changes to prepare a testing profile.
  • Also, VSCode can be used as a debugger. See .vscode/launch.example.json for an example config. Copy to .vscode/launch.json and edit the paths as needed.

Commit

  • Run yarn fix to lint and format the code.
  • Commit your changes. If you're wondering what to write, here's a template:
{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}

Send a pull request

  • Push to your forked repo.
  • Create a pull request on the GitHub website, or your favorite GitHub client.

Code style

  • We mostly adhere to biome defaults for formatting and linting, with some exceptions that reflect my personal preferences.
  • You can adjust .editorconfig and biome.jsonc to your taste locally, but please make sure to run yarn fix with the original config before sending a PR.
  • PRs that suggest adjusting these are also welcome, as long as they don't cause a huge rewrite.

FAQ

Link