From 0ed0799e23505ac6bb9b8facfb9c49a5b0287167 Mon Sep 17 00:00:00 2001 From: Kim Mu-hun Date: Fri, 15 May 2026 06:54:51 +0900 Subject: [PATCH] docs: update the CONTRIBUTING.md (#230176) * docs(contributing): fix branch naming convention Documented `fix/123` didn't match actual team practice. Real convention uses domain suffix: `fix-#{issue}-{domain}`. * docs(contributing): add commit message format Team uses `Fix #N domain` / `Upd #N domain` convention but it wasn't documented for external contributors. * docs(contributing): add rule placement conventions Implicit team practices not previously documented: new rules at section top, domain insertion at list beginning/end, group consistency for same-domain rules. * docs: update branch naming convention to slash-separated format https://github.com/AdguardTeam/AdguardFilters/pull/230176#discussion_r3225315534 * docs: reword rule placement heading sentence https://github.com/AdguardTeam/AdguardFilters/pull/230176#discussion_r3225834464 * docs: clarify same-domain group insertion wording https://github.com/AdguardTeam/AdguardFilters/pull/230176#discussion_r3225858467 * docs: add group comment to same-domain code example https://github.com/AdguardTeam/AdguardFilters/pull/230176#discussion_r3225881989 * docs: bold "beginning" and "at the end" separately https://github.com/AdguardTeam/AdguardFilters/pull/230176#discussion_r3225964987 * docs: replace separate examples with combined mixed-type diff https://github.com/AdguardTeam/AdguardFilters/pull/230176#discussion_r3226023924 * docs: remove label instruction Regular users can't change the label: https://github.com/AdguardTeam/AdguardFilters/pull/230176#discussion_r3226041465 * docs: restructure mixed-type rule placement example Moves the combined mixed-type diff after the type-specific examples so readers see the individual rules first, then the override. Adds a brief reason: only the separator differs (`,` vs `|`), so consistent ordering makes missing domains immediately visible. https://github.com/AdguardTeam/AdguardFilters/pull/230176#discussion_r3233231097 * docs: clarify fix vs upd branch prefix distinction https://github.com/AdguardTeam/AdguardFilters/pull/230176#discussion_r3233187977 * docs: tighten same-rule-expression domain placement bullet Prevents contributors from adding the domain as a new rule on a separate line by making the instruction explicit. https://github.com/AdguardTeam/AdguardFilters/pull/230176#discussion_r3233231097 * better without "or follow-ups" Co-authored-by: Alex * If the rule applies to a site for which a rules group exists... Co-authored-by: Alex * Add "depending on the type of rule" Co-authored-by: Alex * For "cosmetic" rules Co-authored-by: Alex * Update CONTRIBUTING.md Co-authored-by: Alex * Update CONTRIBUTING.md Co-authored-by: Alex * Update CONTRIBUTING.md Co-authored-by: Alex * Remove the avoid notice Co-authored-by: Alex * moved above Co-authored-by: Alex * Update CONTRIBUTING.md Co-authored-by: Alex * Update CONTRIBUTING.md Co-authored-by: Alex * Update CONTRIBUTING.md Co-authored-by: Alex * Fixed linter warnings --------- Co-authored-by: Alex --- CONTRIBUTING.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 87 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ec76fc5b8e..073ee1c724e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,7 +40,20 @@ After you have installed the necessary tools, you need to set up the repository. ## Workflow for submitting changes 1. Create a new branch for your changes. Please use the following naming convention: - `fix/123` where `123` is the issue number you're working on. + - `{prefix}/{description}` + - `{prefix}/{issue-number}-{description}` + - `{prefix}/{third-party-repo-prefix}-{issue-number}-{description}` + + Where `{prefix}` is: + - `fix` — complete fixes or rule additions + - `upd` — minor improvements (e.g. addressing omissions from previous commit, small documentation or comment edits) + + Examples: + - `fix/12345` + - `fix/12345-example.com` + - `fix/ubo-12345-example.com` + - `upd/12345` + 1. Make your changes, test them and put them in the proper file or section of the file. - You can learn how to write filtering rules in the [How to write filter rules][how-to-write-filters] section. - Before creating any rules, please read and understand the current @@ -63,6 +76,79 @@ After you have installed the necessary tools, you need to set up the repository. If AGLint passes, your PR will be reviewed by a maintainer. 1. If the review is successful, your changes will be merged into the `master` branch. +### Rule placement + +- By default, new rules should be placed at the top of the relevant section in the filter file. + + ```diff + !NOTE: Regular rules + + + example.org##.banner-ads + ||example.com/ads/* + ``` + +- If the rule applies to a site for which a rules group exists, insert it **within that group**, rather than at the top + of the section. + + ```diff + ! Example group + ||example.org/images/ads/* + + ||example.org/scripts/tracking.js + example.org##.example-ads + ``` + +- For rules that share the same rule expression, depending on the type of rule, + add the new domain to the existing expression — either at the **beginning** or **at the end**, + rather than creating a new rule on a separate line. + This makes it easy to add a new domain consistently, treating them as a single rule. + + **Important:** Don't insert a new domain at a random position in the middle of the list. + + - For cosmetic rules – at the beginning of the rule: + + ```diff + - example.com,example.org###ads + + test.com,example.com,example.org###ads + ``` + + - In general, for rules with `|` domains separator, add a new domain at the end: + + ```diff + - adserver.com$domain=example.com|example.org + + adserver.com$domain=example.com|example.org|test.com + ``` + + - When the group contains both types, keep domain order consistent across all rules. + + This is because only the separator differs (`,` vs `|`) — + consistent ordering makes it immediately clear that no domains are missing. + + ```diff + -example.com,example.org###ads + +example.com,example.org,test.com###ads + -||example.com^$domain=example.com|example.org + +||example.com^$domain=example.com|example.org|test.com + -||ads.com^$domain=example.com|example.org + +||ads.com^$domain=example.com|example.org|test.com + ``` + +### Commit message format + +- To close an associated issue, use: + +```text +Fix #ISSUE_NUMBER example.org optional description +``` + +- For updates that do not require closing the issue (e.g. problematic issue, an issue with multiple reports, making + changes while solving the problem together with the user) + +```text +Upd #ISSUE_NUMBER example.org description +``` + +If a commit is associated with an issue that has several reports, a link to the comment can be used as the description. + ### Skipping checks If you need to skip running checks, you can do it in the following ways.