diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100755 index 00000000000..99dec5d4553 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1,4 @@ +#!/usr/bin/env sh +. "$(dirname -- "$0")/_/husky.sh" + +yarn run lint diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a9817069a0e..402f4d8285b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,132 +1,205 @@ # 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! +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 -1. Install [Visual Studio Code](https://code.visualstudio.com/download) with the ["Adblock" syntax plugin](https://marketplace.visualstudio.com/items?itemName=adguard.adblock). -2. [Clone](https://docs.github.com/repositories/creating-and-managing-repositories/cloning-a-repository#cloning-a-repository) (or fork and clone) this repo. -3. Make your changes and commit them. -4. 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` - website from the issue. - * `Fix #123 comment` where `comment` is your comment for additional fixes in the pull request. +### Prepare + +1. Install [nodejs][nodejs] and [yarn][yarn]. +2. Install [Visual Studio Code][vscode] with the + ["Adblock" syntax plugin][vscodeplugin]. We recommend using this editor to + write filter rules. +3. [Clone][clonerepo] (or fork and clone) this repo. +4. Run `yarn install` to install necessary dependencies. + +[nodejs]: https://nodejs.org/en/download +[yarn]: https://classic.yarnpkg.com/en/docs/install +[vscode]: https://code.visualstudio.com/download +[vscodeplugin]: https://marketplace.visualstudio.com/items?itemName=adguard.adblock +[clonerepo]: https://docs.github.com/repositories/creating-and-managing-repositories/cloning-a-repository#cloning-a-repository + +### 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](https://kb.adguard.com/general/adguard-filter-policy) we adhere to. One of its most important points is the [quality requirements](https://kb.adguard.com/general/adguard-filter-policy#quality-requirements-for-filtering-rules). +Before you begin, please read and understand the current +[filters policy][policy] we adhere to. One of its most important points is the +[quality requirements][qualityrequirements]. The next step is creating rules. - * There is an [official documentation](https://kb.adguard.com/general/how-to-create-your-own-ad-filters) 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. + +- There is an [official documentation][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. + +[policy]: https://adguard.com/kb/general/ad-filtering/filter-policy/ +[qualityrequirements]: https://adguard.com/kb/general/ad-filtering/filter-policy/#quality-requirements-for-filtering-rules +[documentation]: https://adguard.com/kb/general/ad-filtering/create-own-filters/ ## 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](https://github.com/AdguardTeam/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. +AdGuard filters are compiled from files in this repository. This is an automated +process that is periodically run by scripts in the [FiltersRegistry][registry] +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. +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. + +[registry]: https://github.com/AdguardTeam/FiltersRegistry ### AdGuard Base filter -* Purpose: this filter blocks various kinds of ads mostly on English-language and multilingual sites. -* [Base folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/BaseFilter/sections) -* Notes: The AdGuard Base filter includes [Easylist](https://github.com/easylist/easylist) if you use AdGuard products, so there's no need to add rules which are already in `Easylist`. +- Purpose: this filter blocks various kinds of ads mostly on English-language + and multilingual sites. +- [Base folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/BaseFilter/sections) +- Notes: The AdGuard Base filter includes [Easylist][easylist] if you use + AdGuard products, so there's no need to add rules which are already in + `Easylist`. -### AdGuard Russian filter - -* Purpose: this filter blocks various kinds of ads on Russian-language sites. -* [Russian folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/RussianFilter/sections) - -### AdGuard Chinese filter - -* Purpose: this filter blocks various kinds of ads on Chinese-language sites. -* [Chinese folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/ChineseFilter/sections) -* Notes: The AdGuard Chinese filter includes [Easylist China](https://github.com/easylist/easylistchina) 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](https://github.com/AdguardTeam/AdguardFilters/tree/master/DutchFilter/sections) - -### AdGuard French filter - -* Purpose: this filter blocks various kinds of ads on French-language sites. -* [French folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/FrenchFilter/sections) -* Notes: The AdGuard French filter includes [Liste FR](https://github.com/easylist/listefr) 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](https://github.com/AdguardTeam/AdguardFilters/tree/master/GermanFilter/sections) -* Notes: The AdGuard German filter includes [Easylist Germany](https://github.com/easylist/easylistgermany) 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](https://github.com/AdguardTeam/AdguardFilters/tree/master/JapaneseFilter/sections) - -### AdGuard Spanish filter - -* Purpose: this filter blocks various kinds of ads on Spanish-language and Portuguese-language sites. -* [Spanish folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/SpanishFilter/sections) - -### AdGuard Turkish filter - -* Purpose: this filter blocks various kinds of ads on Turkish-language sites. -* [Turkish folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/TurkishFilter/sections) +[easylist]: https://github.com/easylist/easylist ### AdGuard Mobile filter -* Purpose: this filter blocks various kinds of ads on mobile version of sites. -* [Mobile folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/MobileFilter/sections) - -### AdGuard Social filter - -* Purpose: this filter blocks various kinds of social widgets from sites. -* [Social folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/SocialFilter/sections) - -### AdGuard Filter unblocking search ads and self-promotions - -* Purpose: this filter unblocks search engine result that may be useful to users. -* [UsefulAdsFilter folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/UsefulAdsFilter/sections) - -### AdGuard Annoyances filter - -* Purpose: this filter blocks irritating elements on web pages including cookie notices, third-party widgets and in-page pop-ups. -* [Annoyances folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter) - - 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](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter/Cookies/sections) - - - ### Mobile App Banners - * Purpose: this filter blocks irritating banners that promote mobile apps of websites. - * [MobileApp folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter/MobileApp/sections) - - - ### Popups - * Purpose: this filter blocks all kinds of pop-ups that are not necessary for websites' operation. - * [Popups folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter/Popups/sections) - - - ### Widgets - * Purpose: this filter blocks annoying third-party widgets - online assistants, live support chats, etc. - * [Widgets folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter/Widgets/sections) - - - ### Other Annoyances - * Purpose: this filter blocks irritating elements on web pages that do not fall under the popular categories of annoyances. - * [Other folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter/Other/sections) - -### 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](https://github.com/AdguardTeam/AdguardFilters/tree/master/ExperimentalFilter/sections) +- Purpose: this filter blocks various kinds of ads on mobile version of sites + and in mobile apps. +- [Mobile folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/MobileFilter/sections) ### AdGuard Tracking Protection filter -* Purpose: this filter hides your actions online and helps avoid tracking. -* [Tracking Protection folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/SpywareFilter/sections) +- Purpose: this filter hides your actions online and helps avoid tracking. +- [Tracking Protection folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/SpywareFilter/sections) ### AdGuard URL Tracking filter -* Purpose: this filter removes various kinds of tracking parameters from sites. -* [URL Tracking folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/TrackParamFilter/sections) +- Purpose: this filter removes various kinds of tracking parameters from sites. +- [URL Tracking folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/TrackParamFilter/sections) + +### AdGuard Social filter + +- Purpose: this filter blocks various kinds of social widgets from sites. +- [Social folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/SocialFilter/sections) + +### 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](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter) + + 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](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter/Cookies/sections) + + - #### Mobile App Banners + + - Purpose: this filter blocks irritating banners that promote mobile apps + of websites. + - [MobileApp folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter/MobileApp/sections) + + - #### Popups + + - Purpose: this filter blocks all kinds of pop-ups that are not necessary + for websites' operation. + - [Popups folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter/Popups/sections) + + - #### Widgets + + - Purpose: this filter blocks annoying third-party widgets: online + assistants, live support chats, etc. + - [Widgets folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter/Widgets/sections) + + - #### Other Annoyances + - Purpose: this filter blocks irritating elements on web pages that do not + fall under the popular categories of annoyances. + - [Other folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/AnnoyancesFilter/Other/sections) + +### 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](https://github.com/AdguardTeam/AdguardFilters/tree/master/ExperimentalFilter/sections) + +### AdGuard Filter unblocking search ads and self-promotions + +- Purpose: this filter unblocks search engine result that may be useful to + users. +- [UsefulAdsFilter folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/UsefulAdsFilter/sections) + +### AdGuard Russian filter + +- Purpose: this filter blocks various kinds of ads on Russian-language sites. +- [Russian folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/CyrillicFilters/RussianFilter/sections) + +### AdGuard Ukrainian filter + +- Purpose: this filter blocks various kinds of ads on Ukrainian-language sites. +- [Ukrainian folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/CyrillicFilters/UkrainianFilter/sections) + +### AdGuard Chinese filter + +- Purpose: this filter blocks various kinds of ads on Chinese-language sites. +- [Chinese folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/ChineseFilter/sections) +- Notes: The AdGuard Chinese filter includes [Easylist China][easylistchina] + if you use AdGuard products, so there's no need to add rules which are already + in `Easylist China`. + +[easylistchina]: https://github.com/easylist/easylistchina + +### AdGuard Dutch filter + +- Purpose: this filter blocks various kinds of ads on Dutch-language sites. +- [Dutch folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/DutchFilter/sections) + +### AdGuard French filter + +- Purpose: this filter blocks various kinds of ads on French-language sites. +- [French folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/FrenchFilter/sections) +- Notes: The AdGuard French filter includes [Liste FR][listefr] if you use + AdGuard products, so there's no need to add rules which are already in + `Liste FR`. + +[listefr]: https://github.com/easylist/listefr + +### AdGuard German filter + +- Purpose: this filter blocks various kinds of ads on German-language sites. +- [German folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/GermanFilter/sections) +- Notes: The AdGuard German filter includes [Easylist Germany][easylistgermany] + if you use AdGuard products, so there's no need to add rules which are already + in `Easylist Germany`. + +[easylistgermany]: https://github.com/easylist/easylistgermany + +### AdGuard Japanese filter + +- Purpose: this filter blocks various kinds of ads on Japanese-language sites. +- [Japanese folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/JapaneseFilter/sections) + +### AdGuard Spanish filter + +- Purpose: this filter blocks various kinds of ads on Spanish-language and + Portuguese-language sites. +- [Spanish folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/SpanishFilter/sections) + +### AdGuard Turkish filter + +- Purpose: this filter blocks various kinds of ads on Turkish-language sites. +- [Turkish folder](https://github.com/AdguardTeam/AdguardFilters/tree/master/TurkishFilter/sections) diff --git a/README.md b/README.md index 17928ec945e..15236801e2c 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,77 @@   +

AdGuard Filters

-

The place where ads are actually blocked

+

The place where ad trackers are actually blocked

- Linter workflow status - License: GPL-3.0-only + Linter workflow status + + License: GPL-3.0-only +

- +

+

-This is the place where we create filters for [AdGuard](https://adguard.com/) and other ad blocking software (for instance, uBlock Origin). Every filter represents a set of rules in text format which are used by AdGuard apps and programs to filter advertising and privacy-threatening content (such as banners, pop-ups, trackers etc.). Rules specific for a particular Internet segment (German filter, Russian filter etc.), or serving a specific purpose (Social media filter, Tracking Protection filter etc.) are combined into one list - filter - and can be enabled/disabled all at once. +This is the place where we create filters for [AdGuard][adguard] and other +ad-blocking software, such as uBlock Origin. Each filter consists of a set of +text-based rules that AdGuard apps and programs use to filter out advertisements +and privacy-invasive content like banners, pop-ups, and trackers. Rules specific +to a certain region (e.g., German filter, Russian filter) or serving a specific +purpose (e.g., Social Media filter, Tracking Protection filter) are combined +into a single list, or filter, that can be enabled or disabled all at once. -Our filters are being constantly updated. This repository lets anyone draw our attention to anything from a missed ad to a false positive, thus helping us to modify our filters, make them better and keep up-to-date. +Our filters are constantly updated. This repository allows anyone to bring our +attention to anything from overlooked ads to false positives, helping us refine +our filters, improve them, and keep them current. -We are proud to say that AdGuard Filters are among the most actively developed content blocking filter lists out there. +We are proud of the fact that AdGuard Filters are among the most actively +developed content-blocking filter lists available, if not the most. - +

+ +

+ +[adguard]: https://adguard.com/ ## AdGuard Filters Policy -Our filter policy is available [here](https://kb.adguard.com/general/adguard-filter-policy). +Our filter policy is available [here][policy]. + +[policy]: https://kb.adguard.com/general/adguard-filter-policy ## Contributing to AdGuard -We are blessed to have a community that does not only love AdGuard, but also gives back. A lot of people volunteer in various ways to make other users' experience with AdGuard better, and you can join them! We, on our part, can only be happy to reward the most active members of the community. So, what can you do? +We are blessed to have a community that does not only love AdGuard, but also +gives back. A lot of people volunteer in various ways to make other users' +experience with AdGuard better, and you can join them! We, on our part, can +only be happy to reward the most active members of the community. +So, what can you do? ### Report Issues -To submit a report, please use this [reporting tool](https://agrd.io/report). +To submit a report, please use this [reporting tool][report]. + +[report]: https://agrd.io/report ### Suggest Filtering Rules -You will find a lot of open issues, each one referencing a problem with some website — a missed ad, a false positive etc. — choose any one and suggest your own rules in comments. AdGuard filter engineers will review your suggestions, and if they find them correct, your rules will be added to AdGuard filters. +You will find a lot of open issues, each one referencing a problem with some +website — a missed ad, a false positive etc. — choose any one and suggest your +own rules in comments. AdGuard filter engineers will review your suggestions, +and if they find them correct, your rules will be added to AdGuard filters. -Here is the [official documentation](https://kb.adguard.com/general/how-to-create-your-own-ad-filters) on AdGuard filtering rules syntax. You'll need to read it before you'll be able to create your own filtering rules. +Here is the [official documentation][documentation] on AdGuard filtering rules +syntax. You'll need to read it before you'll be able to create your own +filtering rules. + +[documentation]: https://adguard.com/kb/general/ad-filtering/create-own-filters/ ### Other ways to contribute -Here is [a dedicated page](https://adguard.com/contribute.html) for people willing to contribute to AdGuard. +Here is [a dedicated page][contribute] for people willing to contribute to +AdGuard. + +[contribute]: https://adguard.com/contribute.html diff --git a/package.json b/package.json index 337bddd4f9e..4630d0020a6 100644 --- a/package.json +++ b/package.json @@ -12,9 +12,11 @@ }, "homepage": "https://github.com/AdguardTeam/AdguardFilters#readme", "scripts": { - "lint": "aglint" + "lint": "aglint", + "prepare": "husky install" }, "devDependencies": { - "@adguard/aglint": "1.0.11" + "@adguard/aglint": "1.0.11", + "husky": "^8.0.3" } -} +} \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index ee8007a3f61..dfefa1463dc 100644 --- a/yarn.lock +++ b/yarn.lock @@ -170,6 +170,11 @@ has-flag@^4.0.0: resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-4.0.0.tgz#944771fd9c81c81265c4d6941860da06bb59479b" integrity sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ== +husky@^8.0.3: + version "8.0.3" + resolved "https://registry.yarnpkg.com/husky/-/husky-8.0.3.tgz#4936d7212e46d1dea28fef29bb3a108872cd9184" + integrity sha512-+dQSyqPh4x1hlO1swXBiNb2HzTDN1I2IGLQx1GrBuiqFJfoMrnZWwVmatvSiO+Iz8fBUnf+lekwNo4c2LlXItg== + ignore@^5.2.1: version "5.2.4" resolved "https://registry.yarnpkg.com/ignore/-/ignore-5.2.4.tgz#a291c0c6178ff1b960befe47fcdec301674a6324"