CONTRIBUTING.md

   1 # Contributing guidelines
   2
   3 ## Table of contents
   4
   5 - [Contributing guidelines](#contributing-guidelines)
   6     - [Table of contents](#table-of-contents)
   7     - [Prerequisites](#prerequisites)
   8     - [Contributing to the project](#contributing-to-the-project)
   9         - [Important notes](#important-notes)
  10
  11 ## Prerequisites
  12
  13 You'll need to install the following tools to your system in order to contribute to the project:
  14
  15 - [Node.js][nodejs-download-link] (we recommend the latest LTS version)
  16 - [Git][git-download-link]
  17 - [Visual Studio Code][vscode-download-link] (highly recommended)
  18     - Don't forget to install the [recommended extensions][recommended-vscode-extensions]
  19
  20 ## Contributing to the project
  21
  22 Here is a general workflow for contributing to the project:
  23
  24 1. Install [prerequisites] to your system
  25 1. Fork `hufilter/hufilter-dev` repository on GitHub
  26 1. Clone your forked repository with `git clone`
  27 1. Install dependencies with `yarn`. This will also initialize the Git hooks via the Husky package.
  28 1. Create a new branch for your changes, e.g. `git checkout -b example.com`
  29 1. Make your changes, typically by editing the section files in the [sections][sections-directory] directory, which
  30    contains the section files that are actually contains the filtering rules. You can find more information about the
  31    structure of this directory in the [`sections/README.md`][sections-readme] file.
  32 1. Commit your changes, then push them to your forked repository. If Husky is configured correctly, the Git hooks will
  33    run automatically and will check your changes for errors and don't let you commit invalid changes.
  34 1. Create a pull request from your forked repository's corresponding branch to the `master` branch of the
  35    `hufilter/hufilter-dev` repository
  36 1. Wait for the CI to finish running in the pull request
  37 1. If the CI fails, fix the issues and push your changes to your forked repository's corresponding branch (this will
  38    automatically update the pull request and the CI will run again)
  39 1. If the CI succeeds, wait for the maintainers to review your changes
  40 1. If your changes are accepted, they will be merged into the `master` branch, and they will be deployed to the
  41    [`hufilter/hufilter` repository][hufilter-dev-repo] automatically right after the merge. Please note that it may take
  42    some time while adblockers update their filter lists.
  43
  44 ### Important notes
  45
  46 - If you are creating rules for multiple websites, please create a separate branch for each website and open a separate
  47   pull request for each website. This will make it easier to review your changes. If you are creating large, hard to
  48   review PRs, they will be rejected and you will be asked to split them into smaller PRs.
  49
  50 [git-download-link]: https://git-scm.com/downloads
  51 [hufilter-dev-repo]: https://github.com/hufilter/hufilter-dev
  52 [nodejs-download-link]: https://nodejs.org/en/download/
  53 [prerequisites]: #prerequisites
  54 [recommended-vscode-extensions]: https://github.com/hufilter/hufilter-dev/blob/master/.vscode/extensions.json
  55 [sections-directory]: https://github.com/hufilter/hufilter-dev/blob/master/sections/
  56 [sections-readme]: https://github.com/hufilter/hufilter-dev/blob/master/sections/README.md
  57 [vscode-download-link]: https://code.visualstudio.com/download