Skip to content

Commit 9317c06

Browse files
committed
Added CONTRIBUTING.md
1 parent cfda1a0 commit 9317c06

File tree

1 file changed

+80
-0
lines changed

1 file changed

+80
-0
lines changed

CONTRIBUTING.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Contribution Guidelines
2+
3+
Thank you for your interest in contributing to ClearURLs! To keep our codebase secure, maintainable, and reviewable, please follow these guidelines when submitting Merge/Pull Requests.
4+
5+
## Table of Contents
6+
7+
1. [Getting Started](#getting-started)
8+
2. [Branching and Pull Requests](#branching-and-pull-requests)
9+
3. [Modifying Rules](#modifying-rules)
10+
4. [Adding New Rules](#adding-new-rules)
11+
5. [Testing Your Changes](#testing-your-changes)
12+
6. [Merge Request Size and Organization](#merge-request-size-and-organization)
13+
7. [Commit Messages](#commit-messages)
14+
8. [Security Considerations](#security-considerations)
15+
9. [Review Process](#review-process)
16+
17+
---
18+
19+
## Getting Started
20+
21+
1. Fork the repository and create a new branch for your work.
22+
2. Sync with the upstream `master` branch regularly to avoid merge conflicts:
23+
```bash
24+
git fetch upstream
25+
git checkout master
26+
git merge upstream/master
27+
```
28+
3. Create a topic branch with a descriptive name:
29+
```bash
30+
git checkout -b add-new-tracking-rule
31+
```
32+
33+
## Branching and Pull Requests
34+
35+
- Use feature branches for each logical set of changes.
36+
- Don’t work directly on `master`.
37+
- Open a Merge Request (MR) / Pull Request (PR) against `master` when your feature branch is ready.
38+
39+
## Modifying Rules
40+
41+
> **Important:** Do **not** move, delete, or heavily modify existing rules in a single MR.
42+
43+
- Existing rules in `rules.json` and `rules.min.json` must remain untouched. This prevents accidental removals and helps reviewers focus on new content.
44+
- If you need to refactor or clean up existing rules, create a dedicated MR for that purpose.
45+
46+
## Adding New Rules
47+
48+
1. **Append only:** Add new rules at the *end* of the file. Do not interleave with existing rules.
49+
2. **Rule format:** Follow the JSON schema and naming conventions exactly. See also https://docs.clearurls.xyz/latest/specs/rules/
50+
3. **Documentation:** For each new rule, include:
51+
- A short description of its purpose.
52+
- An example URL containing the tracking parameter(s) you intend to remove.
53+
- (Optional) A brief note on any edge cases or limitations.
54+
55+
## Merge Request Size and Organization
56+
57+
- **Keep MRs small and focused.** Aim for fewer than 200 lines of net additions per MR.
58+
- **One topic per MR:** Group related rules together (e.g., all rules for a given domain).
59+
- If you have a large number of rules to add, split them into multiple MRs.
60+
61+
## Commit Messages
62+
63+
- Write clear, imperative commit messages.
64+
- Reference issue numbers when applicable: `Add rule for example.com (#123)`.
65+
66+
## Security Considerations
67+
68+
- ClearURLs is distributed as a browser extension and integrated into multiple applications, so any faulty or malicious rule could impact hundreds of thousands of users worldwide.
69+
- **Avoid large, unreviewable diffs:** split your changes into focused MRs so reviewers can thoroughly inspect each rule and prevent potential security issues.
70+
71+
## Review Process
72+
73+
- After opening an MR / PR, it will be assigned to a maintainer for review.
74+
- Respond promptly to review comments and clarify any questions.
75+
- Once approved and all CI checks pass, your MR will be merged.
76+
77+
---
78+
79+
We appreciate your contributions and efforts to keep ClearURLs secure and efficient! If you have any questions, feel free to open an issue or ask in the discussion channels.
80+

0 commit comments

Comments
 (0)