Skip to content

Force Proxy to any Windows/MacOS/Linux Application TCP and UDP traffic

docs/ci: contribution rules, per-platform PR templates and an automatic PR check

AnoF-Cyberf96e00b0c9df
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index c5226f3..e23ecf6 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,115 +1,31 @@
-# Pull Request
-
-## ⚠️ IMPORTANT - READ BEFORE SUBMITTING
-
-### Required Pre-Submission Checklist
-
-- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) file
-- [ ] I have created a GitHub issue for this change and linked it below
-- [ ] I have forked the **`dev`** branch (NOT `master`)
-- [ ] I understand that the `master` branch is ONLY updated when a new release is created
-- [ ] I understand that pull requests to `master` will be **REJECTED**
-
-### ⛔ Critical Information
-
-**DO NOT submit a pull request directly to the `master` branch.** The master branch is only updated when a new release is created. No direct commits or merges are accepted to master - neither from the InterceptSuite team nor from contributors.
-
-**All changes MUST be submitted to the `dev` branch**, which contains the latest code and commits.
-
-**You MUST create a GitHub issue first** before submitting a pull request. This allows the InterceptSuite team to:
-- Verify if the bug is already fixed in the development branch
-- Confirm if a new feature is accepted and approved
-- Avoid duplicate work
-
-Pull requests without an associated issue will be rejected.
-
----
-
-## Pull Request Details
-
-### Type of Change
-<!-- Select one -->
-- [ ] Bug Fix
-- [ ] New Feature
-- [ ] Code Improvement/Refactoring
-- [ ] Documentation Update
-- [ ] Other (please describe):
-
-### Related GitHub Issue
-**Issue Link:** <!-- REQUIRED: Paste the link to your GitHub issue here -->
-<!-- Example: https://github.com/InterceptSuite/ProxyBridge/issues/123 -->
-
-### Platform(s) Affected
-<!-- Check all that apply -->
-- [ ] Windows
-- [ ] macOS
-- [ ] Linux
-- [ ] Cross-platform/All
-
----
-
-## macOS Application Changes
-
-### Does this pull request include changes to the macOS application?
-- [ ] Yes
-- [ ] No
-
-**If YES, you MUST answer the following:**
-
-### macOS Code Signing & Verification
-<!-- macOS applications require a valid signature to run. You must verify your changes work. -->
-
-- [ ] I have signed the macOS app with a valid Apple Developer account
-- [ ] I have run the signed application on macOS to verify my changes work as expected
-- [ ] I confirm the application launches and functions correctly with my changes
-
-**⚠️ Important:** If you cannot sign the macOS app to verify your code changes work, please DO NOT submit this pull request. Instead, use the GitHub issue you created to let the InterceptSuite team fix the bug or add the feature. You will need to wait for the next release.
-
----
-
-## Description of Changes
-
-### What does this pull request do?
-<!-- Provide a clear and detailed description of your changes -->
-
-
-### How has this been tested?
-<!-- Describe the tests you ran to verify your changes -->
-- Test environment (OS, version, etc.):
-- Test steps:
-- Test results:
-
-
-### Compilation & Dependencies
-- [ ] I have reviewed the [CONTRIBUTING.md](../CONTRIBUTING.md) file for compilation instructions
-- [ ] I have verified all required libraries and packages are documented
-- [ ] My changes compile without errors
-- [ ] My changes do not introduce new dependencies (or I have documented them below)
-
-**New dependencies (if any):**
-<!-- List any new libraries, packages, or system requirements -->
-
+<!--
+Thank you for contributing to ProxyBridge! 🙌 Please read CONTRIBUTING.md first (it is short and explains why we ask for this).
+
+Quick reminders:
+ - This pull request must target the `dev` branch.
+ - You must have commented on the linked issue BEFORE you started, and heard back from a maintainer.
+ - Fill in each part below. An automatic check looks for the answers and will ask you for anything missing.
+ - Working on macOS? Use the macOS template: add ?template=macos.md to the address of this page
+ (same for ?template=windows.md and ?template=linux.md). macOS changes need the extra signing and testing details.
+-->
+
+## Linked issue
+Fixes #
+<!-- type the issue number right after the #, for example: Fixes #123 -->
+
+## What does this pull request do?
+<!-- What changed and why, in a few sentences. -->
+
+## Tests
+<!-- Write each answer after the question. The platform's automatic checks (CI) run on top of this, but we still need to know what YOU ran. -->
+- **Did you run the tests locally? (which ones, on which system):** <!-- e.g. the commands you ran, and the OS / version -->
+- **Result or output (paste the last lines):** <!-- e.g. "22/22 passed" -->
+- **Did anything fail? (what, and why):** <!-- "no", or what failed and why -->
+- **New tests added (or "none"):** <!-- the files or test names -->
+- **Tests removed or changed (or "none"):** <!-- and why -->
+
+## Anything else? (optional)
+<!-- New dependencies, screenshots or logs, anything a reviewer should know. -->
---
-
-## Screenshots/Logs (if applicable)
-<!-- Add screenshots, error logs, or other supporting materials -->
-
-
----
-
-## Additional Context
-<!-- Add any other context about the pull request here -->
-
-
----
-
-## Final Checklist
-
-- [ ] My code follows the project's coding style
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have updated documentation as needed
-- [ ] My changes do not generate new warnings or errors
-- [ ] I have tested my changes on the target platform(s)
-- [ ] I have verified this change is based on the latest `dev` branch
-- [ ] I understand that pull requests without an associated GitHub issue will be rejected
+By opening this pull request I confirm that it targets `dev`, that I commented on the linked issue before starting, and that I ran the tests listed above.
diff --git a/.github/PULL_REQUEST_TEMPLATE/linux.md b/.github/PULL_REQUEST_TEMPLATE/linux.md
new file mode 100644
index 0000000..afe3276
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/linux.md
@@ -0,0 +1,30 @@
+<!--
+Thank you for contributing to ProxyBridge! 🙌 Please read CONTRIBUTING.md first (it is short and explains why we ask for this).
+
+Quick reminders:
+ - This pull request must target the `dev` branch.
+ - You must have commented on the linked issue BEFORE you started, and heard back from a maintainer.
+ - Fill in each part below. An automatic check looks for the answers and will ask you for anything missing.
+ - Linux template. Other platforms: add ?template=windows.md or ?template=macos.md to the address of this page.
+-->
+
+## Linked issue
+Fixes #
+<!-- type the issue number right after the #, for example: Fixes #123 -->
+
+## What does this pull request do?
+<!-- What changed and why, in a few sentences. -->
+
+## Tests
+<!-- Write each answer after the question. The platform's automatic checks (CI) run on top of this, but we still need to know what YOU ran. -->
+- **Did you run the tests locally? (which ones, on which system):** <!-- e.g. Linux/profile/tests/run_tests.sh, make test-rules, run_relay_test.sh, and the distro + kernel. Root-only e2e tests in Linux/tests if you touched hooks, relay, rules or DNS -->
+- **Result or output (paste the last lines):** <!-- e.g. "22/22 passed" -->
+- **Did anything fail? (what, and why):** <!-- "no", or what failed and why -->
+- **New tests added (or "none"):** <!-- the files or test names -->
+- **Tests removed or changed (or "none"):** <!-- and why -->
+
+## Anything else? (optional)
+<!-- New dependencies, screenshots or logs, anything a reviewer should know. -->
+
+---
+By opening this pull request I confirm that it targets `dev`, that I commented on the linked issue before starting, and that I ran the tests listed above.
diff --git a/.github/PULL_REQUEST_TEMPLATE/macos.md b/.github/PULL_REQUEST_TEMPLATE/macos.md
new file mode 100644
index 0000000..57dcef9
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/macos.md
@@ -0,0 +1,37 @@
+<!--
+Thank you for contributing to ProxyBridge! 🙌 Please read CONTRIBUTING.md first (it is short and explains why we ask for this).
+
+Quick reminders:
+ - This pull request must target the `dev` branch.
+ - You must have commented on the linked issue BEFORE you started, and heard back from a maintainer.
+ - Fill in each part below. An automatic check looks for the answers and will ask you for anything missing.
+ - macOS template. Other platforms: add ?template=windows.md or ?template=linux.md to the address of this page.
+-->
+
+## Linked issue
+Fixes #
+<!-- type the issue number right after the #, for example: Fixes #123 -->
+
+## What does this pull request do?
+<!-- What changed and why, in a few sentences. -->
+
+## macOS signing and testing
+<!-- macOS changes are accepted only if YOU built, signed and ran the app. We can't sign or test it for you. See CONTRIBUTING.md. -->
+- **macOS version and chip:** <!-- e.g. macOS 26.5, Apple M4 -->
+- **Xcode version:** <!-- e.g. 26.6 -->
+- **How you signed the app:** <!-- e.g. Developer ID with my own team and my own bundle IDs -->
+- **Did the signed app run and behave correctly with your change?** <!-- what you saw, and the system extension approved? -->
+
+## Tests
+<!-- Write each answer after the question. The platform's automatic checks (CI) run on top of this, but we still need to know what YOU ran. -->
+- **Did you run the tests locally? (which ones, on which system):** <!-- MacOS/tests/logic/run.sh and MacOS/tests/pbtest.py (the suites you ran) -->
+- **Result or output (paste the last lines):** <!-- e.g. "22/22 passed" -->
+- **Did anything fail? (what, and why):** <!-- "no", or what failed and why -->
+- **New tests added (or "none"):** <!-- the files or test names -->
+- **Tests removed or changed (or "none"):** <!-- and why -->
+
+## Anything else? (optional)
+<!-- New dependencies, screenshots or logs, anything a reviewer should know. -->
+
+---
+By opening this pull request I confirm that it targets `dev`, that I commented on the linked issue before starting, and that I ran the tests listed above.
diff --git a/.github/PULL_REQUEST_TEMPLATE/windows.md b/.github/PULL_REQUEST_TEMPLATE/windows.md
new file mode 100644
index 0000000..705737b
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/windows.md
@@ -0,0 +1,30 @@
+<!--
+Thank you for contributing to ProxyBridge! 🙌 Please read CONTRIBUTING.md first (it is short and explains why we ask for this).
+
+Quick reminders:
+ - This pull request must target the `dev` branch.
+ - You must have commented on the linked issue BEFORE you started, and heard back from a maintainer.
+ - Fill in each part below. An automatic check looks for the answers and will ask you for anything missing.
+ - Windows template. Other platforms: add ?template=macos.md or ?template=linux.md to the address of this page.
+-->
+
+## Linked issue
+Fixes #
+<!-- type the issue number right after the #, for example: Fixes #123 -->
+
+## What does this pull request do?
+<!-- What changed and why, in a few sentences. -->
+
+## Tests
+<!-- Write each answer after the question. The platform's automatic checks (CI) run on top of this, but we still need to know what YOU ran. -->
+- **Did you run the tests locally? (which ones, on which system):** <!-- e.g. the Windows tests, and the Windows version you tested on -->
+- **Result or output (paste the last lines):** <!-- e.g. "22/22 passed" -->
+- **Did anything fail? (what, and why):** <!-- "no", or what failed and why -->
+- **New tests added (or "none"):** <!-- the files or test names -->
+- **Tests removed or changed (or "none"):** <!-- and why -->
+
+## Anything else? (optional)
+<!-- New dependencies, screenshots or logs, anything a reviewer should know. -->
+
+---
+By opening this pull request I confirm that it targets `dev`, that I commented on the linked issue before starting, and that I ran the tests listed above.
diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml
new file mode 100644
index 0000000..567e0b7
--- /dev/null
+++ b/.github/workflows/pr-check.yml
@@ -0,0 +1,178 @@
+name: PR Check
+
+# Checks every pull request against the rules in CONTRIBUTING.md:
+# - wrong base branch (not `dev`) -> closed with a short, friendly comment
+# - missing issue / template details -> `needs-details` label + a friendly comment listing what is missing
+# Maintainers (owner, members, collaborators), branches pushed to this repository, and bots are skipped.
+#
+# pull_request_target runs with the base repository's permissions, so this workflow must NEVER check out or
+# run code from the pull request. It only reads the pull request through the API.
+
+on:
+ pull_request_target:
+ types: [opened, edited, reopened, synchronize, ready_for_review]
+
+permissions:
+ contents: read
+ pull-requests: write
+ issues: write
+
+concurrency:
+ group: pr-check-${{ github.event.pull_request.number }}
+ cancel-in-progress: true
+
+jobs:
+ check:
+ name: Check pull request
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ steps:
+ - name: Check pull request
+ uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+ with:
+ script: |
+ const pr = context.payload.pull_request;
+ const { owner, repo } = context.repo;
+ const number = pr.number;
+ const author = pr.user.login;
+ const MARK = '<!-- pr-check:v1 -->';
+ const LABEL = 'needs-details';
+ const blob = (path) => `https://github.com/${owner}/${repo}/blob/dev/${path}`;
+ const CONTRIBUTING = blob('CONTRIBUTING.md');
+
+ // ---- who is exempt: maintainers, branches in this repository, bots
+ const sameRepo = pr.head.repo && pr.head.repo.full_name === pr.base.repo.full_name;
+ if (pr.user.type === 'Bot' || sameRepo || ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(pr.author_association)) {
+ core.info(`Skipping ${author}: maintainer, same-repository branch or bot`);
+ return;
+ }
+
+ const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number: number, per_page: 100 });
+ const existing = comments.find((c) => c.body && c.body.includes(MARK));
+
+ const hasLabel = (pr.labels || []).some((l) => l.name === LABEL);
+ async function removeLabel() {
+ if (!hasLabel) return;
+ try { await github.rest.issues.removeLabel({ owner, repo, issue_number: number, name: LABEL }); } catch (e) { core.info(`label not removed: ${e.message}`); }
+ }
+ async function upsertComment(text) {
+ const body = `${MARK}\n${text}`;
+ if (existing) {
+ if (existing.body !== body) await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+ } else {
+ await github.rest.issues.createComment({ owner, repo, issue_number: number, body });
+ }
+ }
+
+ // ---- 1. wrong base branch: close with a comment
+ if (pr.base.ref !== 'dev') {
+ await github.rest.issues.createComment({
+ owner, repo, issue_number: number,
+ body: `Thank you for taking the time to contribute! 🙏\n\nPull requests need to be opened against the **\`dev\`** branch. \`${pr.base.ref}\` only changes when we publish a release, so we have to close this one. Please open a new pull request against \`dev\`. The reasons and the other steps are in [CONTRIBUTING.md](${CONTRIBUTING}).`,
+ });
+ await github.rest.pulls.update({ owner, repo, pull_number: number, state: 'closed' });
+ return;
+ }
+
+ // ---- 2. template details
+ const problems = [];
+ const raw = pr.body || '';
+ const text = raw.replace(/<!--[\s\S]*?-->/g, ''); // text the contributor actually wrote
+ const lines = text.split('\n');
+ const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+ // body of the "## <title>" section, up to the next heading
+ function section(title) {
+ const start = lines.findIndex((l) => /^#{1,6}\s/.test(l) && l.toLowerCase().includes(title.toLowerCase()));
+ if (start < 0) return null;
+ let end = lines.length;
+ for (let i = start + 1; i < lines.length; i++) if (/^#{1,6}\s/.test(lines[i])) { end = i; break; }
+ return lines.slice(start + 1, end).join('\n');
+ }
+ const hasText = (s) => !!s && s.replace(/[^\p{L}\p{N}]/gu, '').length > 0;
+ // answer written after the "**label...**" of a field, up to the next field
+ function answer(sec, key) {
+ const m = sec.match(new RegExp('\\*\\*[^*\\n]*' + esc(key) + '[^*\\n]*\\*\\*([\\s\\S]*?)(?=\\n\\s*[-*]\\s+\\*\\*|$)', 'i'));
+ return m ? m[1] : null;
+ }
+ function requireFields(sec, title, fields) {
+ if (sec === null) { problems.push(`The **${title}** section is missing. Please use the pull request template.`); return; }
+ const missing = fields.filter(([key]) => !hasText(answer(sec, key))).map(([, name]) => name);
+ if (missing.length) problems.push(`**${title}**: please answer ${missing.map((m) => `"${m}"`).join(', ')}.`);
+ }
+
+ // which platforms the pull request touches
+ const files = await github.paginate(github.rest.pulls.listFiles, { owner, repo, pull_number: number, per_page: 100 });
+ const touches = (prefix) => files.some((f) => f.filename.startsWith(prefix));
+ const macos = touches('MacOS/');
+
+ // what the pull request does
+ const what = section('What does this pull request do');
+ if (what === null) problems.push('The **pull request template** is missing (or its sections were removed). Please use it: it tells us what changed, why and how you tested it.');
+ else if (what.replace(/[^\p{L}\p{N}]/gu, '').length < 20) problems.push('**What does this pull request do?** is empty or too short. Please describe what you changed and why.');
+
+ // tests
+ requireFields(section('Tests'), 'Tests', [
+ ['run the tests locally', 'Did you run the tests locally?'],
+ ['result or output', 'Result or output'],
+ ['anything fail', 'Did anything fail?'],
+ ['new tests added', 'New tests added'],
+ ['tests removed or changed', 'Tests removed or changed'],
+ ]);
+
+ // macOS changes need the signing and testing details
+ if (macos) {
+ requireFields(section('macOS signing and testing'), 'macOS signing and testing', [
+ ['macos version and chip', 'macOS version and chip'],
+ ['xcode version', 'Xcode version'],
+ ['how you signed', 'How you signed the app'],
+ ['signed app', 'Did the signed app run correctly?'],
+ ]);
+ }
+
+ // linked issue, commented on first, and someone replied before the pull request was opened
+ const refs = new Set();
+ for (const m of text.matchAll(/(?:^|[^\w/])#(\d+)\b/g)) refs.add(Number(m[1]));
+ for (const m of text.matchAll(new RegExp(`github\\.com/${esc(owner)}/${esc(repo)}/issues/(\\d+)`, 'gi'))) refs.add(Number(m[1]));
+ refs.delete(number);
+ let issue = null;
+ for (const n of [...refs].slice(0, 5)) {
+ try {
+ const res = await github.rest.issues.get({ owner, repo, issue_number: n });
+ if (!res.data.pull_request) { issue = res.data; break; }
+ } catch (e) { core.info(`#${n} is not an issue here: ${e.message}`); }
+ }
+ if (!issue) {
+ problems.push('**Linked issue**: please link the GitHub issue this pull request is for (for example `Fixes #123`). If there is no issue yet, please open one and wait for a reply before you start.');
+ } else {
+ const thread = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number: issue.number, per_page: 100 });
+ const before = (c) => new Date(c.created_at) < new Date(pr.created_at);
+ const engaged = issue.user.login === author || thread.some((c) => c.user.login === author && before(c));
+ const replied = (issue.assignees || []).some((a) => a.login === author)
+ || thread.some((c) => c.user.login !== author && c.user.type !== 'Bot' && before(c));
+ if (!engaged) problems.push(`**Linked issue #${issue.number}**: we can't see a comment from you on it before this pull request, saying you would work on it. Please comment on the issue first.`);
+ else if (!replied) problems.push(`**Linked issue #${issue.number}**: we can't see a reply from a maintainer on it yet. Please wait for a reply before you start, so we can confirm it is not already done and fits the project.`);
+ }
+
+ // ---- result
+ if (!problems.length) {
+ if (existing) await upsertComment('✅ Thank you, the required details are there now. A maintainer will take a look when there is time.');
+ await removeLabel();
+ return;
+ }
+ try { await github.rest.issues.getLabel({ owner, repo, name: LABEL }); }
+ catch (e) { await github.rest.issues.createLabel({ owner, repo, name: LABEL, color: 'fbca04', description: 'The pull request is missing details required by CONTRIBUTING.md' }); }
+ if (!hasLabel) await github.rest.issues.addLabels({ owner, repo, issue_number: number, labels: [LABEL] });
+
+ const templates = [
+ `[Windows](${blob('.github/PULL_REQUEST_TEMPLATE/windows.md')})`,
+ `[macOS](${blob('.github/PULL_REQUEST_TEMPLATE/macos.md')})`,
+ `[Linux](${blob('.github/PULL_REQUEST_TEMPLATE/linux.md')})`,
+ ].join(', ');
+ await upsertComment([
+ 'Thank you for the pull request! 🙌 A few details are still missing before we can review it:',
+ '',
+ ...problems.map((p) => `- ${p}`),
+ '',
+ `Please edit the description of this pull request to add them. This comment updates by itself when you do. If you are not sure why we ask for these, [CONTRIBUTING.md](${CONTRIBUTING}) explains it. Templates: ${templates}.`,
+ ].join('\n'));
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 73dbec4..659e2b8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,14 +4,63 @@ Thank you for your interest in contributing to ProxyBridge! We welcome contribut
## Table of Contents
+- [Read This Before You Open a Pull Request](#read-this-before-you-open-a-pull-request)
- [Code of Conduct](#code-of-conduct)
- [How Can I Contribute?](#how-can-i-contribute)
- [Development Setup](#development-setup)
+- [Testing](#testing)
- [Pull Request Process](#pull-request-process)
- [Coding Standards](#coding-standards)
- [Reporting Bugs](#reporting-bugs)
- [Suggesting Features](#suggesting-features)
+## Read This Before You Open a Pull Request
+
+> [!IMPORTANT]
+> **Thank you for wanting to contribute!** Please take a couple of minutes to read this short guide before you start.
+> Pull requests that don't follow it are hard for us to review, so they are usually closed straight away, sometimes without a detailed reply. It is nothing personal. We simply want to protect your time and ours.
+
+### Why we ask for this
+
+We would love to receive your work, and a pull request that follows this guide is warmly welcome. Here is why we ask for a little preparation up front:
+
+- **It looks like one small project, but it is a bigger one.** ProxyBridge is a single repository, but it holds **three different applications with three different code bases**: Windows, macOS and Linux. They share a goal, not code, and they use different languages, drivers, APIs, builds and tests. **One person maintains all of them**, and more platforms (such as Android and iOS) are planned. If you use ProxyBridge on one platform, it is natural to see it as one app. From our side it is three, with more to come.
+- **We want the full picture from the pull request itself.** With this much code on this many platforms, we cannot always tell from a bare pull request what it is for, how it was tested, or whether we already know about it. The template, the linked issue and your test details give us that before we start reviewing.
+- **We keep open the work we have already talked about.** Those are pull requests for a bug or feature we already know about, where someone said on the issue that they would fix it and how, and where the testing is shown. That is why we ask you to comment on the issue first.
+- **The goal is to save effort, yours and ours.** We want to avoid pull requests that don't fit the project's goals, fix something that is already fixed on another branch, or add a bug fix or feature we didn't know about. Those take a lot of time to review and nobody benefits.
+
+If you are unsure about anything, just ask on the issue. That is exactly what it is there for.
+
+### The five things to know
+
+**1. Please open your pull request against `dev`.**
+- Fork the `dev` branch, create your branch from it, and open the pull request against `dev`.
+- `master` only changes when we publish a release. A pull request opened against any other branch is closed right away, usually without a comment, so please double-check the target branch before you create it.
+
+**2. Please fill in the pull request template.**
+- The template tells us **what** you changed, **how**, **why**, **which platform** and **how you tested it**. We need those details to review your work.
+- Use the template for your platform (see [Pull request templates](#pull-request-templates-and-the-automatic-check)). It also asks what tests you ran locally and what the result was, even though the checks on GitHub run too.
+- An **automatic check** looks at every pull request. If something is missing it adds a `needs-details` label and a friendly comment that lists exactly what to add. If the template is removed, if sections are deleted, or if the requested details stay empty, we are not able to review the pull request and it will be closed.
+
+**3. Please link an issue, and comment on it before you start.**
+
+A link to an issue on its own is not enough. Before you write the code, please:
+
+1. **comment on the issue**, saying you would like to fix the bug or add the feature, and
+2. **wait for a maintainer to reply.**
+
+Why: many features and fixes are already done on `dev`, on another branch, or locally on our side, and unreleased work is not visible to you. Some issues are not valid or are not part of the project's goals. A quick comment first saves **you** from building something we cannot use. The automatic check looks at the linked issue: it should exist, show a comment from you before the pull request was opened, and show a reply from someone else. A pull request with no linked issue, or for an issue that was not discussed first, cannot be accepted. Opening a new issue and a pull request at the same time does not count as asking first. If an issue already exists, please comment on it instead of opening a duplicate.
+
+**4. macOS: please sign and test it yourself.**
+- The macOS app needs Apple signing to run its system extension, so we can only accept macOS changes that **you** were able to build, sign and test on a real Mac. See [macOS](#macos) and [Testing](#testing).
+- We are not able to sign, build or test macOS changes on your behalf.
+- macOS has its own test suite in [`MacOS/tests`](MacOS/tests). It runs **locally**, not in GitHub Actions, because a person has to approve the system extension on the Mac. Please tell us in your pull request what you tested and what the results were (macOS version, chip, how you signed, which tests you ran, the output).
+- If you can't sign the app, that is completely fine. Describe the bug or idea on the issue instead, and we will take care of it in a future release.
+
+**5. Please make sure the existing tests pass on every platform.**
+- Pull requests for **all** platforms need to pass the existing tests and checks. See [Testing](#testing) for what runs on each platform.
+- When you fix a bug or change behavior and the platform has a test suite (Linux and macOS do), a new test for it is very welcome.
+
## Code of Conduct
This project and everyone participating in it is governed by our commitment to fostering an open and welcoming environment. We pledge to make participation in our project a harassment-free experience for everyone.
@@ -49,41 +98,7 @@ Feature suggestions are welcome! Please provide:
### Pull Requests
-**IMPORTANT: Open an Issue and WAIT for a Reply Before You Start Coding**
-
-Please read this carefully - it is the most common source of wasted effort.
-
-1. **Create a GitHub Issue First - then wait for maintainer confirmation**
- - Before writing **any** code, **open a GitHub issue** describing the bug you want to fix or the feature you want to add.
- - **Then stop and wait for a maintainer to reply.** Do **not** start coding, and do **not** open a pull request yet.
- - The whole point of the issue is to let us tell you *before you invest time* whether:
- - The feature/fix is **already implemented** in the `dev` branch (not yet released, so you can't see it).
- - It is **already being worked on** by someone else or by us right now.
- - It **doesn't align** with the project's goals and would be declined regardless of quality.
- - Only once a maintainer confirms it's not already done / in progress and that it fits the project should you fork, code, and open a PR.
-
- > [!WARNING]
- > **Opening an issue and a pull request at the same time defeats the purpose.**
- > Several contributors have forked, built a feature, opened a brand-new issue, and immediately opened a PR for it in one go. By then the work is already done - so if the feature was already implemented, already in progress, or out of scope, **your effort is wasted and the PR will be closed.** The issue exists so we can catch that *beforehand*. Please wait for our reply on the issue before you build anything.
-
- - If a GitHub issue for the bug/feature **already exists**:
- - Comment on it saying you'd like to work on it and wait for a maintainer to assign it / give the go-ahead.
- - **Do NOT create a duplicate issue.**
-
-2. **Fork the `dev` Branch**
- - **Always fork and create pull requests against the `dev` branch**
- - **NEVER create pull requests against the `master` branch**
- - The `master` branch is only updated with new releases
- - All development work happens in the `dev` branch
- - Pull requests to `master` will be **automatically rejected**
-
-3. **macOS Code Changes - Apple Developer Account Required**
- - If you are making changes to macOS code, you **MUST**:
- - Have a valid Apple Developer account ($99/year)
- - Have tested your code changes and verified they work as expected
- - Have proper code signing configured (see Apple Signing section below)
- - **Pull requests with untested macOS code will NOT be merged**
- - If you don't have an Apple Developer account and cannot test your changes, your PR will be rejected
+Read [Read This Before You Open a Pull Request](#read-this-before-you-open-a-pull-request) first. In short: pull request to **`dev`** only, **complete template**, a **linked issue you commented on first**, **signed macOS testing** for macOS changes, and **all existing tests passing**.
**Standard Pull Request Process:**
@@ -176,12 +191,13 @@ All compiled files are placed in `Windows/output/` directory:
### macOS
**Prerequisites:**
-- Xcode 15.0 or later
-- macOS 13.0 (Ventura) or later
-- Swift 5.9+
+- A Mac with a recent macOS and **Xcode 16 or later** (the project uses file-system synchronized groups, which need Xcode 16+; we build with the latest stable Xcode)
+- The app supports **macOS 13.0 (Ventura) or later** (that is the project's deployment target) and builds universal (`arm64` and `x86_64`)
+- Swift language mode 5 (`SWIFT_VERSION = 5.0`). **No third-party libraries**: the app uses only Apple frameworks (SwiftUI, AppKit, NetworkExtension, SystemExtensions, ServiceManagement)
- Git
-- **Valid Apple Developer Account** (required for code signing)
+- **Valid Apple Developer Account** (required for code signing and for the System Extension)
- **Provisioning Profiles** installed on your system
+- For the macOS tests: **Python 3** and a **C compiler** (both come with the Xcode command line tools)
**Apple Developer Account & Code Signing:**
@@ -262,6 +278,15 @@ macOS development requires a valid Apple Developer account with proper signing c
**Note:** The `config/` folder is in `.gitignore` to keep your credentials private.
+ **Bundle identifiers:** the identifiers and the app group used by the project (`com.interceptsuite.ProxyBridge`, `com.interceptsuite.ProxyBridge.extension`, `group.com.interceptsuite.ProxyBridge`) belong to InterceptSuite's Apple team, so your team cannot sign with them. Use **your own identifiers** for local signing and testing. Set them in your `config/Signing-Config-*.xcconfig` files and update every place that refers to them. Find all of them with:
+
+ ```bash
+ cd MacOS/ProxyBridge
+ grep -rn "com.interceptsuite" . --exclude-dir=output --exclude-dir=build
+ ```
+
+ The places that matter are `ProxyBridge.xcodeproj/project.pbxproj`, the two `*Release.entitlements` files, `extension/AppProxyProvider.swift` (the extension skips its own traffic by bundle ID), `ProxyBridge/ProxyBridgeViewModel.swift` (the app activates the extension by ID) and `extension/DNSMapStore.swift` (app group). **Do not include your identifier or signing changes in your pull request.**
+
**Setup:**
```bash
# Clone the repository (dev branch)
@@ -324,12 +349,16 @@ You **MUST** create a **Release build** for the Network Extension to function pr
**What build.sh does:**
- Checks for `output/ProxyBridge.app` (exits if not found)
- - Creates PKG installer: `output/ProxyBridge-v3.1-Universal-Installer.pkg`
- - Optionally signs and notarizes the PKG (requires .env file with credentials)
+ - Checks that the app and the extension are **universal** (`arm64` and `x86_64`)
+ - Checks that `VERSION` at the top of `build.sh` matches `MARKETING_VERSION` in the Xcode project (it fails if they differ, so bump both together when the version changes)
+ - Creates the PKG installer `output/ProxyBridge-v<VERSION>-Universal-Installer.pkg`. Its `distribution.xml` declares `hostArchitectures="x86_64,arm64"`, so Apple silicon Macs do not ask to install Rosetta. Keep that attribute
+ - Optionally signs and notarizes the PKG (requires a `.env` file with credentials). Without it you get an unsigned PKG, which is fine for local testing
**Output:**
- `MacOS/ProxyBridge/output/ProxyBridge.app` - Release build (from Xcode Archive)
-- `MacOS/ProxyBridge/output/ProxyBridge-v3.1-Universal-Installer.pkg` - PKG installer (from build.sh)
+- `MacOS/ProxyBridge/output/ProxyBridge-v<VERSION>-Universal-Installer.pkg` - PKG installer (from build.sh)
+
+**Re-installing a rebuilt extension:** macOS only replaces an installed system extension when its version changes. When you rebuild the same version for testing, raise `CURRENT_PROJECT_VERSION` of the **extension** target (in the Xcode project) so the new build replaces the old one. Do not include that bump in your pull request.
**Project Structure:**
- `MacOS/ProxyBridge/ProxyBridge/` - SwiftUI main app
@@ -340,6 +369,68 @@ You **MUST** create a **Release build** for the Network Extension to function pr
- `proxybridge-app.xcconfig` - Template config (in project root)
- `proxybridge-ext.xcconfig` - Template config (in project root)
+### Linux
+
+**Prerequisites** (Debian/Ubuntu package names, the same ones the CI uses):
+`build-essential gcc make clang curl linux-tools-common linux-tools-generic libbpf-dev libelf-dev zlib1g-dev libgtk-3-dev pkg-config`
+
+On Ubuntu `bpftool` is installed with `linux-tools-*` and is not on `PATH`. Point `BPFTOOL` at it (for example `/usr/lib/linux-tools/<kernel>/bpftool`) if the build cannot find it.
+
+```bash
+git clone -b dev https://github.com/InterceptSuite/ProxyBridge.git
+cd ProxyBridge/Linux
+WERROR=1 ./build.sh # builds the library, the CLI and the GUI, results land in Linux/output/
+```
+
+The CI builds with `WERROR=1`, so your change must compile warning-free. See [`Linux/README.md`](Linux/README.md) for usage and the full list of tests.
+
+## Testing
+
+Every pull request must pass the existing tests and checks for the platform it touches. The checks that run automatically on pull requests are in [`.github/workflows`](.github/workflows); the tests that need a real machine are run by you, locally.
+
+| Platform | Runs automatically (GitHub Actions) | You run locally |
+|----------|--------------------------------------|-----------------|
+| **Windows** | `Build Windows` (`compile.ps1 -NoSign`), the Windows tests and `CodeQL` | Test your change on a real Windows machine and describe it in the pull request |
+| **Linux** | `Build Linux` (unit tests, then the build with `WERROR=1`) and `CodeQL` | The root-only end-to-end tests in `Linux/tests` when your change touches the kernel hooks, relay, rules or DNS (see `Linux/README.md`) |
+| **macOS** | `CodeQL`. The signed `Build macOS` workflow uses our signing secrets, which GitHub does not give to pull requests from forks, so its signing steps cannot run for them | **The whole macOS test suite (below). Required.** |
+
+**Linux tests that run in CI** (you can run them too, no root needed):
+
+```bash
+Linux/profile/tests/run_tests.sh # .pbprofile reader/writer, including fuzzing under ASan/UBSan
+cd Linux/src && make test-rules BUILD_DIR=/tmp/pbt # rule engine and DNS parser tests
+cd tests && ./run_relay_test.sh plain # relay tests
+```
+
+### macOS tests
+
+The macOS tests are in [`MacOS/tests`](MacOS/tests) (see its `README.md` for details). They are **not** run in GitHub Actions: the system extension has to be approved by a person on the Mac, which CI cannot do. **You run them on your own signed build and report the results in your pull request.**
+
+1. **Logic tests** - no installed extension needed, they take seconds:
+
+ ```bash
+ MacOS/tests/logic/run.sh
+ ```
+
+ They compile the matcher and DNS-map tests against the real extension sources and run them.
+
+2. **End-to-end tests** - run against your **signed** app with the system extension approved:
+ 1. Install your signed build, start it and approve the system extension and the network configuration when macOS asks.
+ 2. In the app, create a new profile and import `MacOS/tests/pbtest.pbprofile` (it adds five local test proxies and ten rules). Make it the active profile. The test rules redirect `curl`, `nc`, `openssl` and `pbudp` traffic, so switch back to your normal profile afterwards.
+ 3. Run:
+
+ ```bash
+ sudo -v # lets the leaks check run without a prompt
+ python3 MacOS/tests/pbtest.py # about 5 minutes
+ python3 MacOS/tests/pbtest.py --slow # also the 2.5 minute idle-UDP test
+ ```
+
+ The suites cover routing (SOCKS5, HTTP, auth, DIRECT, BLOCK, UDP), proxy reply parsing, per-proxy hostnames, 300 parallel TCP connections and UDP flows (memory must stay flat), DNS, and a `leaks` check on the extension.
+
+3. **Add a test** when you fix a bug or change behavior in the extension: extend `MacOS/tests/pbtest.py` / `servers.py`, or add a logic test in `MacOS/tests/logic`.
+
+**What your macOS pull request must show:** macOS version and chip (Apple silicon or Intel), Xcode version, how you signed the build, which test suites you ran and their result (paste the summary lines), and screenshots or logs for any GUI change.
+
## Pull Request Process
1. **Update documentation** - if your changes affect user-facing features
@@ -349,10 +440,47 @@ You **MUST** create a **Release build** for the Network Extension to function pr
5. **One feature per PR** - keep pull requests focused
6. **Sign your commits** - use `git commit -s`
+### Pull request templates and the automatic check
+
+Pull request descriptions are plain Markdown (GitHub does not support forms for pull requests the way it does for issues), so we kept the template short: type your answer after each question. There is **no checkbox to tick by hand**.
+
+**Pick the template for your platform.** The default template opens automatically. For a platform template, add `?template=<name>.md` to the address of the "Open a pull request" page:
+
+| Platform | Template | Address ending |
+|----------|----------|----------------|
+| Any / cross-platform | the default | (nothing to add) |
+| Windows | `.github/PULL_REQUEST_TEMPLATE/windows.md` | `?template=windows.md` |
+| macOS | `.github/PULL_REQUEST_TEMPLATE/macos.md` | `?template=macos.md` |
+| Linux | `.github/PULL_REQUEST_TEMPLATE/linux.md` | `?template=linux.md` |
+
+**Every template asks about your local tests**, because the GitHub checks do not replace them:
+- Did you run the tests locally (which ones, on which system)?
+- What was the result or output?
+- Did anything fail, and why?
+- Did you add any new tests?
+- Did you remove or change any tests?
+
+The **macOS template** also asks for your macOS version and chip, your Xcode version, how you signed the app, and whether the signed app ran correctly with your change. If your pull request changes anything under `MacOS/`, this part is required whichever template you started from.
+
+**What the automatic check does** (workflow `PR Check`):
+
+| Situation | What happens |
+|-----------|--------------|
+| The pull request targets a branch other than `dev` | It is **closed with a short comment** asking you to open a new one against `dev` |
+| No linked issue, or the issue was not discussed first | `needs-details` label and a friendly comment |
+| Template removed, or required details missing or left empty | `needs-details` label and a friendly comment listing what to add |
+| Everything is there | Nothing. The comment updates and the label is removed once you fix your description |
+
+Maintainers, branches pushed to this repository, and bots are not checked.
+
### PR Checklist
-- [ ] Code builds without errors
-- [ ] All tests pass
+- [ ] The pull request targets **`dev`**
+- [ ] The **pull request template is fully filled in** (nothing removed, nothing left empty)
+- [ ] It links a GitHub issue, and I **commented on that issue and heard back from a maintainer before I started**
+- [ ] Code builds without errors (and without warnings on Linux, `WERROR=1`)
+- [ ] **All existing tests and checks pass** for the platforms I changed
+- [ ] **macOS changes only:** I signed the app myself, tested it on a real Mac, ran the macOS tests, and described the results in the pull request
- [ ] Documentation updated
- [ ] No merge conflicts
- [ ] Commit messages are clear