Contributing to uBlacklist

July 18, 2026 · View on GitHub

This document provides guidelines for contributing to the uBlacklist project, which spans multiple repositories (see Related repositories in the README).

All contributions to any of these repositories follow the flow described below.

How to Contribute

Reporting Bugs and Suggesting Features

Please start with GitHub Discussions instead of opening issues directly.

  • 🐛 Bugs — Report a bug.
  • 💡 Ideas — Suggest a feature.

After verification, the maintainer will convert a discussion to an issue.

Submitting Pull Requests

You can submit a pull request directly, without going through a discussion, only for trivial fixes:

  • Typo or comment fixes.
  • Minimal fixes for an obvious bug.
  • Fixes to existing built-in SERPINFO files.

If you are unsure whether your change is trivial, please ask in a discussion first.

Anything else is a major change and must follow the bug/feature flow above: start with a discussion, wait for the maintainer to convert it to an issue, and then open the pull request referencing that issue. Pull requests for major changes without a preceding discussion or issue may be closed.

You are responsible for the code you submit, including code generated by AI tools. You should be prepared to explain your changes and respond to review feedback.

By submitting a pull request, you agree that your contributions will be licensed under the MIT License.

No New Built-in SERPINFOs

The set of built-in SERPINFO files is intentionally fixed. Discussions and pull requests requesting a new built-in SERPINFO may be closed.

Translation

Please use Crowdin for all translations.

Development

Prerequisites

pnpm >= 10 is required.

Installation

git clone --recurse-submodules https://github.com/iorate/ublacklist.git
cd ublacklist
pnpm install

Build

# Usage: pnpm build [--browser=chrome|firefox|edge|safari] [--debug]
pnpm build --browser=firefox

Output is written to dist/<browser> (or dist/<browser>-debug with --debug).

Check, Test, and Fix

Run all checks and tests before submitting a pull request:

pnpm check  # biome + prettier + typescript
pnpm test

To auto-fix lint and formatting issues:

pnpm fix

Adding or Changing Messages

src/_locales/en/messages.json is the source of truth for English UI messages; other locales are managed via Crowdin.

  1. Edit src/_locales/en/messages.json.
  2. Run pnpm generate:message-names to regenerate the message name constants.

Environment Variables

For developing sync features, create a .env file with your API keys:

DROPBOX_APP_KEY=...
DROPBOX_APP_SECRET=...
GOOGLE_DRIVE_CLIENT_ID=...
GOOGLE_DRIVE_CLIENT_SECRET=...