mirror of https://github.com/ospab/ostp.git
docs: add commit conventions and branch strategy to CONTRIBUTING
- New "Commit Message Conventions" section (type(scope): summary + a body only when the why isn't obvious from the diff) — formalizes the style already used across this rebuild's history. - New "Branch Strategy" section documenting the nightly -> pre-release -> master promotion model (pre-release/master are fast-forward-only, never committed to directly). - Fixed PR/branch-creation instructions that still said "target master" / "branch from master" — contributor work targets nightly now. - Clarified the ostp-control build step is optional for day-to-day core/client/server work (the server embeds a dummy dist/ otherwise).
This commit is contained in:
parent
f96daaf57d
commit
114011df5a
|
|
@ -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)
|
1. [Development Setup](#development-setup)
|
||||||
2. [Project Structure](#project-structure)
|
2. [Project Structure](#project-structure)
|
||||||
3. [Development Workflow](#development-workflow)
|
3. [Branch Strategy](#branch-strategy)
|
||||||
4. [Coding Guidelines](#coding-guidelines)
|
4. [Development Workflow](#development-workflow)
|
||||||
5. [Submitting Pull Requests](#submitting-pull-requests)
|
5. [Commit Message Conventions](#commit-message-conventions)
|
||||||
6. [Security Vulnerabilities](#security-vulnerabilities)
|
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
|
cd ostp
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Build the control panel frontend**:
|
2. **Build the entire Cargo workspace**:
|
||||||
```bash
|
|
||||||
cd ostp-control
|
|
||||||
npm install
|
|
||||||
npm run build
|
|
||||||
cd ..
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Build the entire Cargo workspace**:
|
|
||||||
```bash
|
```bash
|
||||||
cargo build
|
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
|
```bash
|
||||||
cargo test --workspace
|
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
|
## Development Workflow
|
||||||
|
|
||||||
1. **Check for existing issues** or open a new one to discuss proposed changes before starting work.
|
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
|
```bash
|
||||||
|
git checkout nightly
|
||||||
git checkout -b feat/your-feature-name
|
git checkout -b feat/your-feature-name
|
||||||
```
|
```
|
||||||
3. **Implement your changes**, ensuring you write appropriate unit or integration tests.
|
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>(<scope>): <short, imperative summary>
|
||||||
|
|
||||||
|
<optional body — explain WHY, not what; the diff already shows what changed>
|
||||||
|
```
|
||||||
|
|
||||||
|
- **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
|
## 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.
|
* **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
|
```bash
|
||||||
git push origin feat/your-feature-name
|
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.
|
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.
|
4. Verify that GitHub Actions CI runs successfully on your PR.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -10,10 +10,12 @@
|
||||||
|
|
||||||
1. [Подготовка окружения](#подготовка-окружения)
|
1. [Подготовка окружения](#подготовка-окружения)
|
||||||
2. [Структура проекта](#структура-проекта)
|
2. [Структура проекта](#структура-проекта)
|
||||||
3. [Процесс разработки](#процесс-разработки)
|
3. [Стратегия веток](#стратегия-веток)
|
||||||
4. [Правила оформления кода](#правила-оформления-кода)
|
4. [Процесс разработки](#процесс-разработки)
|
||||||
5. [Создание Pull Request](#создание-pull-request)
|
5. [Оформление коммитов](#оформление-коммитов)
|
||||||
6. [Уязвимости безопасности](#уязвимости-безопасности)
|
6. [Правила оформления кода](#правила-оформления-кода)
|
||||||
|
7. [Создание Pull Request](#создание-pull-request)
|
||||||
|
8. [Уязвимости безопасности](#уязвимости-безопасности)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -33,20 +35,19 @@
|
||||||
cd ostp
|
cd ostp
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Соберите веб-интерфейс панели управления**:
|
2. **Соберите весь Cargo-workspace**:
|
||||||
```bash
|
|
||||||
cd ostp-control
|
|
||||||
npm install
|
|
||||||
npm run build
|
|
||||||
cd ..
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Соберите весь Cargo-workspace**:
|
|
||||||
```bash
|
```bash
|
||||||
cargo build
|
cargo build
|
||||||
```
|
```
|
||||||
|
`ostp-control` (веб-панель) нужна только если вы работаете конкретно над
|
||||||
|
ней — в остальных случаях сервер собирается с пустым `dist/` через
|
||||||
|
`rust-embed`, и этот шаг не нужен для повседневной работы над
|
||||||
|
core/client/server. Если вы всё же трогаете панель:
|
||||||
|
```bash
|
||||||
|
cd ostp-control && npm install && npm run build && cd ..
|
||||||
|
```
|
||||||
|
|
||||||
4. **Запустите тесты**:
|
3. **Запустите тесты**:
|
||||||
```bash
|
```bash
|
||||||
cargo test --workspace
|
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) для обсуждения предлагаемых изменений.
|
1. **Проверьте существующие задачи** или откройте новую тему (Issue) для обсуждения предлагаемых изменений.
|
||||||
2. **Сделайте fork репозитория** и создайте новую ветку от `master`:
|
2. **Сделайте fork репозитория** и создайте новую ветку от `nightly`:
|
||||||
```bash
|
```bash
|
||||||
|
git checkout nightly
|
||||||
git checkout -b feat/имя-вашей-фичи
|
git checkout -b feat/имя-вашей-фичи
|
||||||
```
|
```
|
||||||
3. **Внесите необходимые изменения** и добавьте соответствующие модульные или интеграционные тесты.
|
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: ...`.
|
* **Безопасность (Safety)**: Избегайте использования блоков `unsafe` везде, где это возможно. Допускается их использование только для низкоуровневых системных вызовов (например, FFI-настройки сокетов `setsockopt`). Любой блок `unsafe` должен сопровождаться комментарием `// SAFETY: ...`.
|
||||||
|
|
@ -104,7 +149,7 @@
|
||||||
```bash
|
```bash
|
||||||
git push origin feat/имя-вашей-фичи
|
git push origin feat/имя-вашей-фичи
|
||||||
```
|
```
|
||||||
2. Создайте Pull Request (PR) в ветку `master` основного репозитория.
|
2. Создайте Pull Request (PR) в ветку `nightly` основного репозитория (см. [Стратегия веток](#стратегия-веток) — `master` получает только fast-forward от `pre-release`, PR туда не принимаются напрямую).
|
||||||
3. Подробно опишите внесенные изменения: какая проблема решается, как проводилось тестирование и на каких платформах проверялась сборка.
|
3. Подробно опишите внесенные изменения: какая проблема решается, как проводилось тестирование и на каких платформах проверялась сборка.
|
||||||
4. Убедитесь, что автоматическое тестирование (GitHub Actions CI) завершилось успешно.
|
4. Убедитесь, что автоматическое тестирование (GitHub Actions CI) завершилось успешно.
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue