diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 25e5827..9039eb6 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -31,6 +31,7 @@ /.github/workflows/ci.yml @igor04091968 @rachkovii68-bisness /.github/workflows/security.yml @igor04091968 @rachkovii68-bisness /.github/workflows/coverage.yml @igor04091968 @rachkovii68-bisness +/.github/GOVERNANCE.md @igor04091968 @rachkovii68-bisness /.github/pull_request_template.md @igor04091968 @rachkovii68-bisness /.github/ISSUE_TEMPLATE/ @igor04091968 @rachkovii68-bisness /.github/CODEOWNERS @igor04091968 @rachkovii68-bisness @@ -38,6 +39,9 @@ /docs/BRANCH_PROTECTION_EVIDENCE_RU.md @igor04091968 @rachkovii68-bisness /docs/PR_REVIEW_WORKFLOW_RU.md @igor04091968 @rachkovii68-bisness /docs/PR_REVIEW_EVIDENCE_RU.md @igor04091968 @rachkovii68-bisness +/docs/ENTERPRISE_QUALITY_STANDARD_RU.md @igor04091968 @rachkovii68-bisness +/docs/OPERATIONS_VALIDATION_RUNBOOK_RU.md @igor04091968 @rachkovii68-bisness +/docs/OPERATIONAL_MATURITY_RU.md @igor04091968 @rachkovii68-bisness # Ansible deployment automation. /ansible/ @igor04091968 @rachkovii68-bisness diff --git a/.github/GOVERNANCE.md b/.github/GOVERNANCE.md new file mode 100644 index 0000000..0da4fd5 --- /dev/null +++ b/.github/GOVERNANCE.md @@ -0,0 +1,41 @@ +# AWatch-rus Governance + +GitHub is the public mirror validation surface. Primary registry release +evidence must be produced on the Russian build-runner and primary operational +context remains the private Gitea contour. + +## Production-first standard + +AWatch-rus is already deployed in a real company. Production stability has +absolute priority. The canonical engineering standard is: + +- [Enterprise quality standard](../docs/ENTERPRISE_QUALITY_STANDARD_RU.md) +- [Review checklist](../docs/REVIEW_CHECKLIST_RU.md) +- [Operational validation runbook](../docs/OPERATIONS_VALIDATION_RUNBOOK_RU.md) +- [Operational maturity harness](../docs/OPERATIONAL_MATURITY_RU.md) + +## Required PR evidence + +Every PR must state: + +- Purpose. +- Operational impact. +- Risk assessment. +- Rollback strategy. +- Validation steps. +- Documentation changes. +- Acceptance criteria. + +Documentation-only or governance-only PRs must explicitly state that runtime, +API and UI behavior are unchanged. + +## Guardrails + +- Prefer additive, backward-compatible changes. +- Do not redesign working subsystems without measured benefit. +- Do not add dependencies without justification and validation. +- Do not weaken authentication, authorization, audit logging, secret handling, + dependency hygiene or configuration validation. +- Do not enable heavy DLP, Loki or always-on Velociraptor during routine + recovery, validation or public CI. +- Keep blocking CI fast; keep heavy/load/nightly checks scheduled or advisory. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8ebaeb7..9e5a518 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,6 +2,12 @@ Describe what changed and why. +## Purpose + +State the production-quality purpose of the change. Prefer reliability, +operational maturity, security, maintainability, reproducibility, performance +or simplicity over new functionality. + ## Impact - Runtime impact: `none / changed / not applicable` @@ -11,14 +17,45 @@ Describe what changed and why. - Rollback impact: `none / documented / not applicable` - Evidence impact: `none / registry docs updated / release evidence required` +## Operational Impact + +Describe deployment, upgrade, rollback, observability, diagnostics, +configuration, recovery, performance or dependency-hygiene impact. + +## Risk Assessment + +List production risks and why the change is backward-compatible. For +documentation-only or governance-only changes, state that runtime/API/UI behavior +is unchanged. + +## Rollback Strategy + +State how to revert the change. Runtime, automation, config and dependency +changes need an explicit rollback path. + ## Validation List commands executed. Use `skipped: ` when a check requires a live stand or unavailable tool. +## Documentation Changes + +List README/runbook/architecture/governance updates, or state `not applicable` +with a reason. + +## Acceptance Criteria + +List concrete conditions that make the PR safe to merge. + ## Review Checklist - [ ] Linked issue is provided, or the PR explains why no issue is applicable. +- [ ] Purpose, operational impact, risk assessment, rollback strategy, + validation steps, documentation changes and acceptance criteria are stated. +- [ ] Change is additive/backward-compatible, or breaking impact is explicitly + blocked for this stage. +- [ ] Production stability is preserved for existing deployments. +- [ ] No working subsystem is redesigned without measured benefit. - [ ] Runtime/API/UI impact is stated. - [ ] Registry claims are checked and remain conservative. - [ ] Secrets, PII, employee logs and customer identifiers are absent. @@ -33,6 +70,8 @@ stand or unavailable tool. - [ ] I checked registry claims: no completed registry submission, no FSTEC/FSB certification claim, no SIEM/DLP replacement claim. - [ ] I ran relevant checks or documented why a check was skipped. +- [ ] I checked dependency impact: no unnecessary dependency was added, and no + unused dependency remains in touched crates. - [ ] I stated runtime/API/UI impact. - [ ] I stated documentation impact. - [ ] I stated smoke-test result or why smoke testing is not applicable. @@ -48,6 +87,12 @@ stand or unavailable tool. build-runner. - Update `docs/registry/` when registry-readiness behavior or evidence changes. +## Governance + +- Production-first standard: `.github/GOVERNANCE.md`. +- Canonical review checklist: `docs/REVIEW_CHECKLIST_RU.md`. +- Canonical validation runbook: `docs/OPERATIONS_VALIDATION_RUNBOOK_RU.md`. + ## Safety - No secrets, tokens, passwords or private keys. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b2bb990..68a4b7f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,11 @@ GitHub is public mirror validation only. Primary registry release evidence is produced separately on the Russian build-runner and documented under `docs/registry/`. +All contributions must follow the production-first governance entrypoint: +`.github/GOVERNANCE.md`. AWatch-rus is already deployed in a real company, so +reliability, operational maturity, security and backward compatibility take +priority over new functionality. + ## Branching - Работайте в feature-ветке, не пушьте напрямую в `main`. @@ -49,6 +54,11 @@ produced separately on the Russian build-runner and documented under ## PR content - Изменения и обоснование. -- Риск и rollback. +- Purpose. +- Operational impact. +- Risk assessment. +- Rollback strategy. - Какие команды валидации были выполнены. +- Documentation changes. +- Acceptance criteria. - Какие проверки были пропущены и почему, если пропуск был необходим. diff --git a/README.md b/README.md index a57557e..912183b 100755 --- a/README.md +++ b/README.md @@ -271,8 +271,16 @@ collectors. ### Engineering governance and residual risks +- Enterprise quality standard: + [docs/ENTERPRISE_QUALITY_STANDARD_RU.md](docs/ENTERPRISE_QUALITY_STANDARD_RU.md). +- GitHub governance entrypoint: + [.github/GOVERNANCE.md](.github/GOVERNANCE.md). - Review checklist: [docs/REVIEW_CHECKLIST_RU.md](docs/REVIEW_CHECKLIST_RU.md). +- Operational validation runbook: + [docs/OPERATIONS_VALIDATION_RUNBOOK_RU.md](docs/OPERATIONS_VALIDATION_RUNBOOK_RU.md). +- Operational maturity harness: + [docs/OPERATIONAL_MATURITY_RU.md](docs/OPERATIONAL_MATURITY_RU.md). - Residual risks register: [docs/RESIDUAL_RISKS_RU.md](docs/RESIDUAL_RISKS_RU.md). - Public issues plan: diff --git a/docs/ENTERPRISE_QUALITY_STANDARD_RU.md b/docs/ENTERPRISE_QUALITY_STANDARD_RU.md new file mode 100644 index 0000000..26901b0 --- /dev/null +++ b/docs/ENTERPRISE_QUALITY_STANDARD_RU.md @@ -0,0 +1,122 @@ +# AWatch-rus: enterprise quality standard + +Дата актуализации: 2026-07-01. + +AWatch-rus уже работает в production-контуре заказчика. Основная цель +разработки - не добавление функций, а повышение надежности, эксплуатационной +зрелости, безопасности, сопровождаемости и воспроизводимости. + +Приоритеты изменений, по убыванию: + +1. Reliability. +2. Operational maturity. +3. Security. +4. Maintainability. +5. Reproducibility. +6. Performance. +7. Simplicity. + +Новые функции не должны иметь приоритет над стабильностью production. + +## Production-first правила + +- Предполагать, что production deployment существует и пользователи зависят от + непрерывной работы. +- Предпочитать additive/backward-compatible изменения. +- Не перепроектировать работающие подсистемы без измеримой пользы. +- Не включать heavy DLP, Loki или always-on Velociraptor без отдельного + operator-approved решения. +- Не менять ActivityWatch logical host ids, bucket suffixes, Grafana variables + или ClickHouse workforce keys без отдельной compatibility-процедуры. +- Fail closed для security-sensitive и deployment-sensitive paths. +- Сохранять rollback path для runtime, automation, config и dependency changes. + +## Порядок принятия решений + +Перед реализацией любого изменения ответ должен быть положительным хотя бы на +один вопрос: + +1. Улучшает ли это production stability? +2. Снижает ли это operational risk? +3. Улучшает ли это diagnostics или observability? +4. Улучшает ли это maintainability? +5. Уменьшает ли это технический долг с низким regression risk? + +Если ответ отрицательный на все пять вопросов, изменение не должно попадать в +production-oriented PR. + +## Dependencies + +Перед добавлением зависимости нужно явно обосновать: + +- почему стандартной библиотеки недостаточно; +- почему существующий workspace crate не решает задачу; +- operational cost зависимости; +- maintenance cost зависимости; +- license/security impact. + +Неиспользуемые зависимости удаляются отдельными низкорисковыми PR после +targeted tests. Обновление `Cargo.lock` без причины не допускается. + +## Required PR sections + +Каждый PR обязан содержать: + +- Purpose. +- Operational impact. +- Risk assessment. +- Rollback strategy. +- Validation steps. +- Documentation changes. +- Acceptance criteria. + +Для documentation-only/governance-only PR нужно явно указать, что runtime, API и +UI impact отсутствуют. + +## Validation baseline + +Канонический набор проверок описан в +`docs/OPERATIONS_VALIDATION_RUNBOOK_RU.md`. Минимальный baseline для +существенных Rust/runtime changes: + +```bash +cd /mnt/usb_hdd2/Projects/ActivityWatch-Russian/adk-rust +export CARGO_TARGET_DIR=/home/igor/.cache/detmir-adk-rust-target + +cargo fmt --all --check +cargo test --workspace --all-targets --locked +cargo test --workspace --doc --locked +cargo clippy --workspace --all-targets --locked -- -D warnings +cargo audit --deny warnings + +cd /mnt/usb_hdd2/Projects/ActivityWatch-Russian +cargo deny --manifest-path adk-rust/Cargo.toml check \ + --config deny.toml \ + --hide-inclusion-graph \ + --show-stats +python3 scripts/public_secret_pattern_check.py +node scripts/operational-maturity-check.mjs --json +``` + +Targeted checks are acceptable for small docs/governance or isolated changes, +but skipped checks must have a concrete reason. + +## Technical debt policy + +Fix technical debt only when all conditions are true: + +- change is isolated; +- regression risk is low; +- tests or operational smoke cover the touched behavior; +- documentation remains accurate. + +Otherwise create a follow-up task or document the residual risk instead of +mixing broad cleanup into a functional PR. + +## Canonical references + +- Review checklist: `docs/REVIEW_CHECKLIST_RU.md`. +- Validation runbook: `docs/OPERATIONS_VALIDATION_RUNBOOK_RU.md`. +- Operational maturity harness: `docs/OPERATIONAL_MATURITY_RU.md`. +- PR workflow: `docs/PR_REVIEW_WORKFLOW_RU.md`. +- GitHub governance entrypoint: `.github/GOVERNANCE.md`. diff --git a/docs/REVIEW_CHECKLIST_RU.md b/docs/REVIEW_CHECKLIST_RU.md index a8332a1..941e942 100644 --- a/docs/REVIEW_CHECKLIST_RU.md +++ b/docs/REVIEW_CHECKLIST_RU.md @@ -2,7 +2,7 @@ Дата: 2026-06-22 -Статус: advisory checklist for public review process. +Статус: canonical checklist for production-first PR review. Этот документ описывает проверочный чеклист для pull requests и внешнего инженерного review. Он не утверждает, что внешний peer review уже выполняется @@ -13,7 +13,15 @@ release evidence должен производиться на российско ## Общая безопасность изменений +- Изменение соответствует production-first стандарту: + `docs/ENTERPRISE_QUALITY_STANDARD_RU.md`. +- Цель PR относится к reliability, operational maturity, security, + maintainability, reproducibility, performance или simplicity. Если PR добавляет + функциональность, он также объясняет measurable operational benefit. - Изменение имеет понятную цель, ограниченный scope and documented impact. +- Изменение additive/backward-compatible, если нет отдельного + operator-approved breaking-change решения. +- Не перепроектируются работающие подсистемы без измеримой пользы. - Нет секретов, токенов, паролей, приватных ключей, recovery codes or live credentials. - Нет персональных данных сотрудников, реальных employee logs or customer @@ -52,6 +60,8 @@ release evidence должен производиться на российско - No runtime behavior is changed by documentation/governance-only PRs. - No service restart, migration or production config change is implied unless explicitly documented. +- Existing production deployment remains compatible, including logical host ids, + bucket suffixes, Grafana variables and ClickHouse workforce keys. ## Registry-readiness impact @@ -80,6 +90,9 @@ release evidence должен производиться на российско - README, `docs/PROJECT_STATUS_RU.md`, registry docs and operational runbooks are updated when claims, checks, workflows or procedures change. +- Behavior changes update the relevant runbook and validation commands. +- Architecture docs are updated when an interface, data flow, deployment + boundary or security boundary changes. - New claims are conservative and evidence-backed. - Pending work remains marked as planned/pending until evidence exists. - Public mirror wording remains separate from registry release evidence. @@ -88,6 +101,8 @@ release evidence должен производиться на российско - PR states whether deployment action is required. - Rollback path is documented for runtime or automation changes. +- Dependency changes are isolated, justified and include rollback by reverting + the dependency/lockfile PR. - Documentation-only PRs state that runtime/API/UI impact is unchanged. - Changes to scripts include syntax checks and a clear operator failure mode. @@ -103,6 +118,9 @@ release evidence должен производиться на российско - For Rust/product changes, use `docs/OPERATIONS_VALIDATION_RUNBOOK_RU.md` as the default local validation contour. +- Dependency hygiene and operational maturity checks are expected when touched + files can affect Rust dependencies, runtime contracts, configuration, + migrations, observability or CI governance. - For operator-facing web, gateway, worktime reports or Grafana dashboards, browser smoke through the rendered pages is required in addition to API checks.