CONTRIBUTING.md

   1 <!-- omit in toc -->
   2 # Contributing guidelines
   3
   4 **🇭🇺 [Kattints ide a magyar nyelvű változatért][hu-version].**
   5
   6 Table of contents:
   7
   8 - [Prerequisites](#prerequisites)
   9 - [Setting up the project](#setting-up-the-project)
  10 - [Adding new rules](#adding-new-rules)
  11
  12 ## Prerequisites
  13
  14 Before contributing to the project, make sure you have the following tools installed on your system:
  15
  16 - [Node.js][nodejs-download-link] (we recommend the latest LTS version)
  17 - [Git][git-download-link]
  18
  19 For an enhanced development experience, we recommend using [Visual Studio Code][vscode-download-link] as your code
  20 editor. If you opt for VS Code, consider installing the [recommended extensions][recommended-vscode-extensions] of the
  21 project.
  22
  23 ## Setting up the project
  24
  25 1. Fork [`hufilter/hufilter`][hufilter-repo] repository on GitHub.
  26 2. Clone your forked repository.
  27 3. Enable Corepack by running the `corepack enable` command. Corepack comes pre-installed with Node.js, so you don't
  28    need to install it separately.
  29 4. Install project dependencies using the `pnpm install` command. If you don't have pnpm installed,
  30    Corepack will prompt you to install it if you run the `pnpm` command.
  31
  32 ## Adding new rules
  33
  34 > [!IMPORTANT]
  35 > hufilter extends EasyList and EasyPrivacy lists. Ensure your rules are not already present in those lists.
  36
  37 1. Create a new branch for your changes, e.g., `git checkout -b example.com` or `git checkout -b fix/123` (for example
  38    if you fix an issue with ID `123`). It's crucial to separate changes by creating a new branch for each
  39    website / issue.
  40 2. Make your changes by editing the section files in the [sections][sections-directory] directory, which contains the
  41    filtering rules. Refer to the [`sections/README.md`][sections-readme] file for information on the directory
  42    structure.
  43 3. Commit your changes, then push them to your forked repository.
  44 4. Create a pull request from your forked repository's corresponding branch to the `master` branch of the
  45    `hufilter/hufilter` repository.
  46 5. Wait for the review of your changes.
  47
  48 <!--markdownlint-disable MD013-->
  49 > [!TIP]
  50 > If you are not familiar with the syntax of the filtering rules, check the following documentations:
  51 >
  52 > - <img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px"> [Adblock Plus: *How to write filters*][abp-filters]
  53 > - <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px"> [AdGuard: *How to create your own ad filters*][adg-filters]
  54 > - <img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px"> [uBlock Origin: *Static filter syntax*][ubo-filters]
  55 >
  56 > These documentations assumes that you are familiar with the basics of web technologies, such as HTML, CSS, and JavaScript.
  57 <!--markdownlint-enable MD013-->
  58
  59 [abp-filters]: https://help.adblockplus.org/hc/en-us/articles/360062733293
  60 [adg-filters]: https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters
  61 [git-download-link]: https://git-scm.com/downloads
  62 [hu-version]: https://github.com/hufilter/hufilter/blob/master/CONTRIBUTING.hu.md
  63 [hufilter-repo]: https://github.com/hufilter/hufilter
  64 [nodejs-download-link]: https://nodejs.org/en/download/
  65 [recommended-vscode-extensions]: https://github.com/hufilter/hufilter/blob/master/.vscode/extensions.json
  66 [sections-directory]: https://github.com/hufilter/hufilter/blob/master/sections/
  67 [sections-readme]: https://github.com/hufilter/hufilter/blob/master/sections/README.md
  68 [ubo-filters]: https://github.com/gorhill/uBlock/wiki/Static-filter-syntax
  69 [vscode-download-link]: https://code.visualstudio.com/download