AdguardFilters/CONTRIBUTING.md

Contributing to AdGuard filters

If you want to make AdGuard better by creating new rules, follow the instructions below to make your ideas come to life faster!

How to work with the repo

Prepare

1. Install nodejs and yarn.
2. Install Visual Studio Code with the "Adblock" syntax plugin. We recommend using this editor to write filter rules.
3. Clone (or fork and clone) this repo.
4. Run yarn install to install necessary dependencies.

Workflow

1. Make your changes and commit them.
2. Each commit should be linked to an issue. The commit message should look like the examples below. That way, the issue will be closed automatically once the commit is merged into the master branch.
   • Fix #123 example.org where 123 is the issue number and example.org is the website from the issue.
   • Fix #123 comment where comment is your comment for additional fixes in the pull request.

How to write filter rules

Before you begin, please read and understand the current filters policy we adhere to. One of its most important points is the quality requirements.

The next step is creating rules.

• There is an official documentation that can help you.
• When you're done with creating rules, please take a look at the similar ones in the filters. This may help you to make a better version of the rule.

Repository structure

AdGuard filters are compiled from files in this repository. This is an automated process that is periodically run by scripts in the FiltersRegistry repo. In this repository, each filter list is divided into several files, and each file has its own purpose. If you're adding a new rule, make sure it is added to the proper file or section of the file.

General requirements for submitting rules: don't add rules to the beginning of the file, start entering them from line 4, for example. If you add rules with a task comment or hints, put them next to the same structure in the file.

AdGuard Base filter

• Purpose: this filter blocks various kinds of ads mostly on English-language and multilingual sites.
• Base folder
• Notes: The AdGuard Base filter includes Easylist if you use AdGuard products, so there's no need to add rules which are already in Easylist.

AdGuard Mobile filter

• Purpose: this filter blocks various kinds of ads on mobile version of sites and in mobile apps.
• Mobile folder

AdGuard Tracking Protection filter

• Purpose: this filter hides your actions online and helps avoid tracking.
• Tracking Protection folder

AdGuard URL Tracking filter

• Purpose: this filter removes various kinds of tracking parameters from sites.
• URL Tracking folder

AdGuard Social filter

• Purpose: this filter blocks various kinds of social widgets from sites.
• Social folder

AdGuard Annoyances filters

• Purpose: this filter blocks irritating elements on web pages including cookie notices, third-party widgets and in-page pop-ups.

• Annoyances folder

  Contains the following AdGuard filters: Cookie Notices, Popups, Mobile App Banners, Other Annoyances and Widgets:

  • Cookie Notices

    • Purpose: this filter blocks cookie notices on web pages.
    • Cookies folder

  • Mobile App Banners

    • Purpose: this filter blocks irritating banners that promote mobile apps of websites.
    • MobileApp folder

  • Popups

    • Purpose: this filter blocks all kinds of pop-ups that are not necessary for websites' operation.
    • Popups folder

  • Widgets

    • Purpose: this filter blocks annoying third-party widgets: online assistants, live support chats, etc.
    • Widgets folder

  • Other Annoyances

    • Purpose: this filter blocks irritating elements on web pages that do not fall under the popular categories of annoyances.
    • Other folder

AdGuard Experimental filter

• Purpose: this filter serves to test some new filtering rules that can potentially cause conflicts and mess with websites' work. In case these rules perform without any issues, they get added to main filters.
• Experimental folder

AdGuard Filter unblocking search ads and self-promotions

• Purpose: this filter unblocks search engine result that may be useful to users.
• UsefulAdsFilter folder

AdGuard Russian filter

• Purpose: this filter blocks various kinds of ads on Russian-language sites.
• Russian folder

AdGuard Ukrainian filter

• Purpose: this filter blocks various kinds of ads on Ukrainian-language sites.
• Ukrainian folder

AdGuard Chinese filter

• Purpose: this filter blocks various kinds of ads on Chinese-language sites.
• Chinese folder
• Notes: The AdGuard Chinese filter includes Easylist China if you use AdGuard products, so there's no need to add rules which are already in Easylist China.

AdGuard Dutch filter

• Purpose: this filter blocks various kinds of ads on Dutch-language sites.
• Dutch folder

AdGuard French filter

• Purpose: this filter blocks various kinds of ads on French-language sites.
• French folder
• Notes: The AdGuard French filter includes Liste FR if you use AdGuard products, so there's no need to add rules which are already in Liste FR.

AdGuard German filter

• Purpose: this filter blocks various kinds of ads on German-language sites.
• German folder
• Notes: The AdGuard German filter includes Easylist Germany if you use AdGuard products, so there's no need to add rules which are already in Easylist Germany.

AdGuard Japanese filter

• Purpose: this filter blocks various kinds of ads on Japanese-language sites.
• Japanese folder

AdGuard Spanish filter

• Purpose: this filter blocks various kinds of ads on Spanish-language and Portuguese-language sites.
• Spanish folder

AdGuard Turkish filter

• Purpose: this filter blocks various kinds of ads on Turkish-language sites.
• Turkish folder