diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7451020..0d34c56 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,10 +10,12 @@ By contributing to this project, you agree to abide by our code of conduct and l 1. [Development Setup](#development-setup) 2. [Project Structure](#project-structure) -3. [Development Workflow](#development-workflow) -4. [Coding Guidelines](#coding-guidelines) -5. [Submitting Pull Requests](#submitting-pull-requests) -6. [Security Vulnerabilities](#security-vulnerabilities) +3. [Branch Strategy](#branch-strategy) +4. [Development Workflow](#development-workflow) +5. [Commit Message Conventions](#commit-message-conventions) +6. [Coding Guidelines](#coding-guidelines) +7. [Submitting Pull Requests](#submitting-pull-requests) +8. [Security Vulnerabilities](#security-vulnerabilities) --- @@ -33,20 +35,19 @@ To build and test OSTP locally, you will need: cd ostp ``` -2. **Build the control panel frontend**: - ```bash - cd ostp-control - npm install - npm run build - cd .. - ``` - -3. **Build the entire Cargo workspace**: +2. **Build the entire Cargo workspace**: ```bash cargo build ``` + `ostp-control` (the web panel) is only needed if you're working on it + specifically — the server build embeds a dummy `dist/` via `rust-embed` + otherwise, so this step is not required for day-to-day core/client/server + work. If you *are* touching the panel: + ```bash + cd ostp-control && npm install && npm run build && cd .. + ``` -4. **Run tests**: +3. **Run tests**: ```bash cargo test --workspace ``` @@ -66,11 +67,28 @@ The repository is organized as a Cargo workspace containing the following crates --- +## Branch Strategy + +The repository runs three long-lived branches, in increasing order of stability: + +| Branch | Role | +|---|---| +| `nightly` | Active development. All feature work and fixes land here first. | +| `pre-release` | Periodically fast-forwarded from `nightly` once it's had some soak time. Ships as the `{version}-beta` release channel. | +| `master` | Fast-forwarded from `pre-release` when it's proven stable. Real, tagged releases (`vX.Y.Z`) are cut from here. | + +`pre-release` and `master` are **never** committed to directly — they only ever move forward by fast-forwarding from the branch below them. This means promotion is always a plain `git merge` with zero conflicts by construction: don't `git merge`/rebase feature work directly onto `pre-release` or `master`. + +**Contributor PRs target `nightly`**, not `master`. + +--- + ## Development Workflow 1. **Check for existing issues** or open a new one to discuss proposed changes before starting work. -2. **Fork the repository** and create a new branch from `master`: +2. **Fork the repository** and create a new branch from `nightly`: ```bash + git checkout nightly git checkout -b feat/your-feature-name ``` 3. **Implement your changes**, ensuring you write appropriate unit or integration tests. @@ -89,6 +107,32 @@ The repository is organized as a Cargo workspace containing the following crates --- +## Commit Message Conventions + +``` +(): + + +``` + +- **Type** — one of: `feat` (new capability), `fix` (bug fix), `docs`, `refactor` (no behavior change), `perf`, `test`, `chore` (deps/tooling/version bumps), `ci`, `security`. +- **Scope** (optional) — the crate or area touched: `client`, `server`, `core`, `gui`, `flutter`, `ci`, `docs`, etc. e.g. `fix(client): ...`. +- **Summary** — imperative mood ("add", not "added"/"adds"), no trailing period, ideally under ~70 characters. +- **Body** — only when the *why* isn't obvious from the diff: a prior bug this fixes, a constraint that shaped the approach, a tradeoff you made. Don't restate what the diff already shows. Wrap at ~72 columns. + +``` +fix(server): drop junk frames by per-key marker instead of a global one + +A fixed 4-byte marker on every junk packet is itself a DPI signature any +observer can filter on across every OSTP deployment. Derive the marker +from the access key (HKDF, same scheme as obfuscation_key/psk) so it's +per-user and indistinguishable from the packet's own random payload. +``` + +Multiple unrelated changes belong in separate commits, not one bundled commit — it keeps `git bisect` and review useful. Squash-merge is fine for a PR with a few "fix typo" / "address review" commits, but don't squash logically distinct changes together. + +--- + ## Coding Guidelines * **Safety**: Avoid using `unsafe` blocks unless absolutely necessary for low-level system bindings (e.g., FFI configurations like `setsockopt`). When using `unsafe`, add safety doc comments explaining why it is safe. @@ -104,7 +148,7 @@ The repository is organized as a Cargo workspace containing the following crates ```bash git push origin feat/your-feature-name ``` -2. Open a Pull Request (PR) targeting the `master` branch. +2. Open a Pull Request (PR) targeting the `nightly` branch (see [Branch Strategy](#branch-strategy) — `master` only receives fast-forwards from `pre-release`, never direct PRs). 3. In your PR description, explain the rationale behind your changes, what was fixed/added, and how it was tested. 4. Verify that GitHub Actions CI runs successfully on your PR. diff --git a/CONTRIBUTING.ru.md b/CONTRIBUTING.ru.md index 2b4b6f5..dbeeee3 100644 --- a/CONTRIBUTING.ru.md +++ b/CONTRIBUTING.ru.md @@ -10,10 +10,12 @@ 1. [Подготовка окружения](#подготовка-окружения) 2. [Структура проекта](#структура-проекта) -3. [Процесс разработки](#процесс-разработки) -4. [Правила оформления кода](#правила-оформления-кода) -5. [Создание Pull Request](#создание-pull-request) -6. [Уязвимости безопасности](#уязвимости-безопасности) +3. [Стратегия веток](#стратегия-веток) +4. [Процесс разработки](#процесс-разработки) +5. [Оформление коммитов](#оформление-коммитов) +6. [Правила оформления кода](#правила-оформления-кода) +7. [Создание Pull Request](#создание-pull-request) +8. [Уязвимости безопасности](#уязвимости-безопасности) --- @@ -33,20 +35,19 @@ cd ostp ``` -2. **Соберите веб-интерфейс панели управления**: - ```bash - cd ostp-control - npm install - npm run build - cd .. - ``` - -3. **Соберите весь Cargo-workspace**: +2. **Соберите весь Cargo-workspace**: ```bash cargo build ``` + `ostp-control` (веб-панель) нужна только если вы работаете конкретно над + ней — в остальных случаях сервер собирается с пустым `dist/` через + `rust-embed`, и этот шаг не нужен для повседневной работы над + core/client/server. Если вы всё же трогаете панель: + ```bash + cd ostp-control && npm install && npm run build && cd .. + ``` -4. **Запустите тесты**: +3. **Запустите тесты**: ```bash cargo test --workspace ``` @@ -66,11 +67,28 @@ --- +## Стратегия веток + +В репозитории три долгоживущие ветки, по возрастанию стабильности: + +| Ветка | Роль | +|---|---| +| `nightly` | Активная разработка. Вся новая работа и фиксы попадают сюда первыми. | +| `pre-release` | Периодически перематывается вперёд (fast-forward) от `nightly`, когда та немного «отлежалась». Собирается в канал релиза `{версия}-beta`. | +| `master` | Перематывается вперёд от `pre-release`, когда та доказала стабильность. Настоящие тегированные релизы (`vX.Y.Z`) режутся отсюда. | + +В `pre-release` и `master` **никогда** не коммитят напрямую — они только перематываются вперёд от ветки уровнем ниже. Это значит, что промоушен — всегда обычный `git merge` без единого конфликта по построению: не мержите/не ребейзьте свою фичу прямо в `pre-release` или `master`. + +**PR от контрибьюторов нацелены на `nightly`**, не на `master`. + +--- + ## Процесс разработки 1. **Проверьте существующие задачи** или откройте новую тему (Issue) для обсуждения предлагаемых изменений. -2. **Сделайте fork репозитория** и создайте новую ветку от `master`: +2. **Сделайте fork репозитория** и создайте новую ветку от `nightly`: ```bash + git checkout nightly git checkout -b feat/имя-вашей-фичи ``` 3. **Внесите необходимые изменения** и добавьте соответствующие модульные или интеграционные тесты. @@ -89,6 +107,33 @@ --- +## Оформление коммитов + +``` +<тип>(<область>): <краткое описание в повелительном наклонении> + +<опционально: тело — объясняет ПОЧЕМУ, а не что; диф и так показывает что изменилось> +``` + +- **Тип** — один из: `feat` (новая функциональность), `fix` (исправление бага), `docs`, `refactor` (без изменения поведения), `perf`, `test`, `chore` (зависимости/тулинг/версии), `ci`, `security`. +- **Область** (опционально) — крейт или часть проекта: `client`, `server`, `core`, `gui`, `flutter`, `ci`, `docs` и т.д., например `fix(client): ...`. +- **Краткое описание** — повелительное наклонение ("добавь", а не "добавил"/"добавляет"), без точки в конце, желательно до ~70 символов. +- **Тело** — только когда причина не очевидна из дифа: какой баг это чинит, какое ограничение определило подход, на какой trade-off вы пошли. Не пересказывайте то, что и так видно в дифе. Перенос строк на ~72 символах. + +``` +fix(server): отбрасывать junk-фреймы по маркеру для каждого ключа, а не глобальному + +Фиксированный 4-байтовый маркер на каждом junk-пакете сам по себе — сигнатура +DPI, по которой можно фильтровать любого наблюдателя во всех деплойментах OSTP +сразу. Выводим маркер из access_key (HKDF, та же схема что у +obfuscation_key/psk), чтобы он был индивидуальным для ключа и неотличимым от +случайной полезной нагрузки пакета. +``` + +Несколько несвязанных изменений — это несколько отдельных коммитов, а не один сборный. Это сохраняет пользу от `git bisect` и код-ревью. Squash-merge подходит для PR с парой коммитов вроде "fix typo" / "address review", но не сквошьте вместе логически разные изменения. + +--- + ## Правила оформления кода * **Безопасность (Safety)**: Избегайте использования блоков `unsafe` везде, где это возможно. Допускается их использование только для низкоуровневых системных вызовов (например, FFI-настройки сокетов `setsockopt`). Любой блок `unsafe` должен сопровождаться комментарием `// SAFETY: ...`. @@ -104,7 +149,7 @@ ```bash git push origin feat/имя-вашей-фичи ``` -2. Создайте Pull Request (PR) в ветку `master` основного репозитория. +2. Создайте Pull Request (PR) в ветку `nightly` основного репозитория (см. [Стратегия веток](#стратегия-веток) — `master` получает только fast-forward от `pre-release`, PR туда не принимаются напрямую). 3. Подробно опишите внесенные изменения: какая проблема решается, как проводилось тестирование и на каких платформах проверялась сборка. 4. Убедитесь, что автоматическое тестирование (GitHub Actions CI) завершилось успешно.