efs-sbom 1.0.0__tar.gz

efs_sbom-1.0.0/.cdxgenrc.example

@@ -0,0 +1,11 @@
+{
+  "spec-version": "1.6",
+  "profile": "generic",
+  "required-only": true,
+  "include-formulation": false,
+  "include-crypto": false,
+  "auto-compositions": false,
+  "no-babel": true,
+  "json-pretty": true,
+  "output": "bom.json"
+}

efs_sbom-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,49 @@
+name: Ошибка
+description: Сообщить о некорректной работе efs
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: Что произошло
+      description: Опишите проблему и чего вы ожидали вместо этого.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Как воспроизвести
+      description: Команда efs целиком и, если возможно, минимальный SBOM-файл или конфиг.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: output
+    attributes:
+      label: Вывод команды
+      description: Полный вывод, включая traceback. Запустите с флагом -v для подробностей.
+      render: shell
+
+  - type: input
+    id: version
+    attributes:
+      label: Версия efs
+      description: "Вывод команды: pip show efs-sbom"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Версия Python и ОС
+      placeholder: "3.12.7, Ubuntu 24.04"
+    validations:
+      required: true
+
+  - type: input
+    id: scanner
+    attributes:
+      label: Инструмент генерации SBOM
+      description: Если проблема связана со сканированием — cdxgen или trivy и его версия.

efs_sbom-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Вопрос по использованию
+    url: https://github.com/happykust/efs/discussions
+    about: Задайте вопрос в обсуждениях, если это не ошибка и не предложение
+  - name: Уязвимость безопасности
+    url: https://github.com/happykust/efs/security/advisories/new
+    about: Сообщайте об уязвимостях приватно, а не через issue

efs_sbom-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: Предложение
+description: Предложить новую возможность или улучшение
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Какую задачу это решает
+      description: Опишите ситуацию, в которой текущих возможностей не хватает.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Предлагаемое решение
+      description: Как это могло бы работать — команда, флаг, поле конфига.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Альтернативы
+      description: Что вы пробовали или рассматривали вместо этого.
+
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Область
+      options:
+        - label: Требования ФСТЭК / ГОСТ Р 56939-2024
+        - label: Генерация SBOM (cdxgen, trivy)
+        - label: Валидация и схемы
+        - label: Экспорт (CSV, ODT)
+        - label: Конфигурация

efs_sbom-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Что меняется
+
+<!-- Коротко: что и зачем. Если есть связанный issue — укажите «Closes #N». -->
+
+## Как проверено
+
+<!-- Какие тесты добавлены или какие сценарии проверены вручную. -->
+
+## Чеклист
+
+- [ ] `uv run pytest` проходит
+- [ ] `uv run ruff check .` и `uv run ruff format --check .` проходят
+- [ ] Добавлены тесты на новое поведение или на исправленный баг
+- [ ] Изменение, заметное пользователю, добавлено в `CHANGELOG.md`
+- [ ] Документация обновлена (README, если менялся интерфейс команд)

efs_sbom-1.0.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: "ci"
+
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: "build"
+    groups:
+      dev-dependencies:
+        patterns: ["pytest*", "ruff", "responses"]

efs_sbom-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,94 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Линтер и форматирование
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check --output-format=github .
+      - run: uv run ruff format --check .
+
+  test:
+    name: Тесты (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run pytest -q --cov=efs --cov-report=term-missing
+
+  build:
+    name: Сборка пакета
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv build
+      - name: Проверка метаданных дистрибутивов
+        run: uvx twine check dist/*
+      - name: Проверка данных пакета в wheel
+        run: |
+          python3 - <<'PY'
+          import glob, sys, zipfile
+
+          required = (
+              "efs/schemas/schema.json",
+              "efs/schemas/schema_container.json",
+              "efs/additional_schemas/spdx.schema.json",
+              "efs/additional_schemas/jsf-0.82.schema.json",
+              "efs/odt_templates/template.odt",
+              "efs/odt_templates/template_container.odt",
+          )
+          names = set(zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist())
+          missing = [item for item in required if item not in names]
+          if missing:
+              sys.exit("в wheel отсутствуют файлы: " + ", ".join(missing))
+          print("данные пакета на месте")
+          PY
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  smoke:
+    name: Проверка установленного пакета
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: astral-sh/setup-uv@v7
+      - name: Установка из wheel и запуск команд
+        run: |
+          uv venv
+          uv pip install dist/*.whl
+          uv run efs --help
+          uv run efs check examples/example-sbom.json
+          uv run efs export csv examples/example-sbom.json /tmp/components.csv

efs_sbom-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Сборка дистрибутивов
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run pytest -q
+      - run: uv build
+      - run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Публикация в PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/efs-sbom
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+
+  github-release:
+    name: Релиз на GitHub
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true

efs_sbom-1.0.0/.github/workflows/sbom.yml

@@ -0,0 +1,41 @@
+name: SBOM
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  self-sbom:
+    name: SBOM самого efs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+      - run: npm install -g @cyclonedx/cdxgen
+      - run: uv sync --locked
+      - name: Генерация и постобработка SBOM
+        run: |
+          uv run efs scan --tool cdxgen --target . --output bom.raw.json
+          uv run efs postprocess bom.raw.json efs.sbom.json \
+            --app-name efs \
+            --app-version "${GITHUB_REF_NAME#v}" \
+            --manufacturer "Kirill Nikolaevskiy"
+      - name: Валидация результата
+        run: |
+          uv run efs check efs.sbom.json || status=$?
+          if [ "${status:-0}" = "1" ]; then
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v7
+        with:
+          name: efs-sbom
+          path: efs.sbom.json

efs_sbom-1.0.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Сборка и дистрибутивы
+build/
+dist/
+
+# Виртуальные окружения
+venv/
+.venv/
+env/
+
+# Тесты и покрытие
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+
+# Локальные артефакты SBOM и конфиги
+*.sbom.json
+bom.json
+.sbom-config.json
+.purl_to_vcs.json
+.purl_to_gost.json
+.purl_exclude.json
+.cdxgenrc
+
+# Локальные инструкции для агентов и рабочие заметки
+CLAUDE.md
+docs/superpowers/

efs_sbom-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

efs_sbom-1.0.0/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+Все значимые изменения проекта фиксируются в этом файле.
+
+Формат основан на [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/),
+проект следует [семантическому версионированию](https://semver.org/lang/ru/).
+
+## [1.0.0] — 2026-08-29
+
+Первый выпуск под именем `efs-sbom`. Раздел «Изменено» описывает, чем релиз
+отличается от предшественника — пакета `sbom-utils`, который не публиковался.
+
+### Изменено (breaking)
+
+- `efs check` возвращает осмысленный код: `0` — перечень готов, `1` — ошибки схемы
+  или недоступные ссылки, `3` — схема в порядке, но перечень не заполнен. Прежде
+  команда всегда завершалась с кодом `0`, из-за чего не годилась для CI. Код `2`
+  оставлен за ошибками вызова, как принято в click.
+- Проект переименован в **efs** (Easy FSTEC SBOMs).
+  - Дистрибутив на PyPI: `efs-sbom` (имя `efs` там занято чужим пакетом).
+  - Python-пакет: `sbom_utils` → `efs`.
+  - CLI-команда: `sbom` → `efs`.
+  - Модуль `sbom_utils.sbom_utils` → `efs.utils`.
+  - Модуль `sbom_utils.cdxgen_postprocess` → `efs.postprocess` (обрабатывает вывод
+    и cdxgen, и trivy, прежнее имя вводило в заблуждение).
+  - Каталог кеша: `~/.cache/sbom-checker` → `~/.cache/efs`. Прежний кеш не
+    переносится — при первом запуске проверки выполняются заново.
+  - Имя файла конфигурации `.sbom-config.json` не изменилось.
+- Удалён неиспользуемый слой argparse из модулей (`configure_parser()`, `main()`,
+  `if __name__ == '__main__'`). Прямой вызов модулей вида
+  `python -m sbom_utils.updater` больше не поддерживается — используйте `efs update`.
+- Удалён `requirements.txt`: зависимости описаны в `pyproject.toml`, версии
+  зафиксированы в `uv.lock`.
+
+### Добавлено
+
+- Набор тестов на pytest и конфигурация ruff.
+- CI на GitHub Actions: линтер, тесты на Python 3.12/3.13/3.14, сборка пакета
+  с проверкой состава wheel и запуск команд из установленного дистрибутива.
+- Публикация в PyPI по тегу через trusted publishing, релиз на GitHub с дистрибутивами.
+- Workflow генерации SBOM самого efs (cdxgen → postprocess → check) на релизных тегах.
+- `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, шаблоны issue и pull request,
+  конфигурация Dependabot.
+- Пример заполненного перечня — `examples/example-sbom.json`.
+- Документация в `docs/`: руководство по подготовке перечня под ФСТЭК, справочник
+  команд и описание конфига. README сокращён до точки входа.
+- Поле `source_langs` в конфиге: языки задаются списком или строкой и попадают в
+  SBOM отдельным свойством `GOST:source_langs` на каждый язык, как требует ФСТЭК.
+  Для большинства экосистем (pypi, npm, maven, cargo, golang, gem, nuget и других)
+  язык определяется по типу purl автоматически; `deb` и `rpm` заполняются вручную.
+  `efs config init` подставляет язык в конфиг, `efs config status` показывает
+  компоненты без языка.
+- Экспорт в CSV и ODT выводит все языки компонента, а не только первый.
+- В графу источника отчётной формы попадает название сертифицированного СЗИ из
+  `GOST:provided_by`, если ссылки на исходный код нет. Прежде графа оставалась
+  пустой, хотя `efs check` считал такой компонент заполненным.
+- `efs postprocess` сохраняет `description` у образов контейнеров: это графа
+  «Назначение» отчётной формы, и постобработка её стирала.
+- `efs check --format container` сообщает об образах без назначения.
+- `efs --version` (`-V`) печатает версию.
+- `efs check --check-vcs` показывает, сколько ссылок проверяется, и отмечает
+  прогресс на длинных перечнях.
+- Мастер `efs init` завершается проверкой готовности перечня, а результат
+  постобработки пишет в отдельный файл, не перезаписывая исходный SBOM.
+- `efs merge` переносит языки в сводный перечень: компонент-сервис наследует языки
+  своих компонентов, включая вложенные. Прежде сводный перечень гарантированно не
+  проходил проверку готовности.
+- `efs update --props`, `--gost` и `--fix-all` проставляют язык, следующий из purl.
+- Значения `--format`, `--tool` и `--gost-default` проверяются и подсказываются
+  автодополнением; неверное значение отвергается с перечнем допустимых.
+- Входные файлы проверяются на существование: вместо трассировки стека выводится
+  сообщение об ошибке, а команда завершается ненулевым кодом. Прежде `efs check`
+  на отсутствующем файле печатал traceback и возвращал `0`.
+- `efs postprocess` проставляет `GOST:source_langs` и без конфига: язык следует из
+  purl и не зависит от того, описан ли компонент в `.efs-config.json`. Прежде
+  проверка требовала язык, а заполнить его без конфига было нечем.
+- Компоненты, которые `efs postprocess` дописывает в конфиг, сразу получают язык,
+  выведенный из экосистемы, — как и при `efs config init`.
+- `efs check` проверяет готовность перечня к сдаче: заглушки `TODO` в метаданных,
+  отсутствие ГОСТ-свойств и `GOST:source_langs`, компоненты без ссылки на
+  репозиторий и без `GOST:provided_by`. В конце печатается сводка по видам
+  замечаний. Отдельного флага нет — проверка выполняется всегда.
+- `efs merge` объединяет сырые отчёты trivy: компоненты дедуплицируются по purl,
+  уязвимости — по CVE, зависимости пересопоставляются, компоненты-манифесты и
+  висячие ссылки отбрасываются. Смешивание trivy-отчётов с обычными SBOM
+  завершается ошибкой.
+- `NOTICE` с атрибуцией ИСП РАН как автора исходного проекта sbom-checker.
+- Поддержка значения `exclude: "direct"` в конфиге — исключение самого компонента
+  без каскадного удаления его транзитивных зависимостей.
+- Резолверы VCS-ссылок для PyPI, npm, Maven, RPM и Deb в `efs update`.
+- Параллельная обработка purl при поиске VCS-ссылок.
+- Команда `efs config migrate` — была описана в README, но отсутствовала в CLI.
+
+### Производительность
+
+- Проверка уникальности элементов вынесена из JSON Schema в отдельный линейный
+  проход. jsonschema сравнивает элементы массивов попарно, из-за чего `efs check`
+  на перечне с тысячами зависимостей работал квадратично: полная проверка
+  реального SBOM (6933 компонента, 6892 зависимости) занимала 39 секунд, а
+  на 100 000 компонентов не завершалась за разумное время. Стало 11 и 47 секунд
+  соответственно, для валидного перечня на 1370 компонентов — около секунды.
+
+### Исправлено
+
+- Сопоставление purl в `exclude` учитывает версию: запись `pkg:npm/ajv@6.12.6`
+  больше не удаляет из SBOM все версии `ajv`.
+- Каскадное `exclude: true` действительно удаляет транзитивные зависимости, как и
+  описано в документации. Прежде корни графа вычислялись уже после отбрасывания
+  рёбер исключённого компонента, из-за чего его зависимости сами становились
+  корнями и сохранялись — каскад не работал ни в одном практическом случае.
+  Защита от удаления «осиротевших» рантайм-зависимостей сохранена: корнями
+  считаются узлы без входящих рёбер в исходном графе.
+- HTTP-фоллбэк при таймауте `git ls-remote` — крупные репозитории (например,
+  chromium) больше не помечаются как недоступные.
+- Неинтерактивный режим для `svn ls` и `hg identify` — проверка VCS не зависает
+  в ожидании ввода учётных данных.
+- Тайм-ауты для всех HTTP-запросов в `efs update`.
+- `efs check --check-source-distribution` завершался исключением на каждой ссылке:
+  `is_archive_url` вызывался без HTTP-сессии. Ошибки внутри параллельных проверок
+  больше не игнорируются — файл не объявляется корректным.
+- `rich` добавлен в явные зависимости: модули использовали его, полагаясь на
+  транзитивную установку через typer.
+
+## Предыстория
+
+Проект вырос из `sbom-checker` (ИСП РАН) и до переименования назывался
+`sbom-utils`: единая CLI-точка входа, единый конфиг, команды `check`, `update`,
+`merge`, `postprocess`, `scan`, `export`, `config`, `init`. Под именем `sbom-utils`
+пакет не публиковался, поэтому первым выпуском считается 1.0.0 под именем
+`efs-sbom`.
+
+[1.0.0]: https://github.com/happykust/efs/releases/tag/v1.0.0

efs_sbom-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Кодекс поведения участников
+
+## Наше обязательство
+
+Мы, участники и сопровождающие проекта, обязуемся сделать участие в сообществе свободным от притеснений для всех — независимо от возраста, телосложения, видимых или невидимых особенностей, пола, уровня опыта, образования, социального статуса, национальности, внешности, расы, религии, сексуальной ориентации и идентичности.
+
+## Наши стандарты
+
+Примеры поведения, которое создаёт здоровую атмосферу:
+
+- уважение к чужому мнению и опыту;
+- конструктивная критика и готовность её принимать;
+- признание своих ошибок и извинения перед теми, кого они затронули;
+- забота об интересах сообщества, а не только о собственных.
+
+Примеры неприемлемого поведения:
+
+- сексуализированные высказывания и внимание любого рода;
+- троллинг, оскорбления, уничижительные комментарии, личные и политические нападки;
+- публичное или приватное притеснение;
+- публикация чужих личных данных без явного разрешения;
+- иное поведение, неуместное в профессиональной среде.
+
+## Применение
+
+Сопровождающие проекта отвечают за разъяснение этих стандартов и принимают справедливые меры в ответ на неприемлемое поведение: от удаления комментариев и коммитов до временного или постоянного запрета на участие.
+
+О случаях неприемлемого поведения сообщайте сопровождающему проекта: me@happykust.dev. Все жалобы рассматриваются оперативно и справедливо, приватность заявителя соблюдается.
+
+## Область действия
+
+Кодекс действует во всех пространствах проекта, а также когда участник официально представляет проект в публичном пространстве.
+
+## Источник
+
+Документ адаптирован из [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), версия 2.1.

efs_sbom-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Участие в разработке
+
+Спасибо за интерес к efs. Здесь описано, как собрать проект, что проверяется в CI и как оформлять изменения.
+
+## Быстрый старт
+
+```bash
+git clone https://github.com/happykust/efs.git
+cd efs
+uv sync
+uv run efs --help
+```
+
+`uv sync` ставит и рантайм-зависимости, и dev-группу (pytest, ruff). Отдельного шага установки для разработки не нужно.
+
+## Проверки перед отправкой изменений
+
+```bash
+uv run pytest            # тесты
+uv run ruff check .      # линтер
+uv run ruff format .     # форматирование
+```
+
+Ровно эти три команды выполняет CI на Python 3.12, 3.13 и 3.14. Если они проходят локально, сборка на GitHub тоже пройдёт.
+
+## Тесты
+
+Тесты лежат в `tests/`, фикстуры и конструкторы минимальных SBOM — в `tests/conftest.py`.
+
+Правило без исключений: **тесты не ходят в сеть и не запускают внешние процессы**. HTTP мокается через `responses`, вызовы `subprocess` и функции проверки репозиториев — через `monkeypatch`. Тест, которому нужен реальный `git`, `cdxgen` или доступ к API, написан неправильно.
+
+Для нового кода тест обязателен. Для исправления бага — сначала тест, воспроизводящий ошибку.
+
+## Стиль кода
+
+- Python 3.12+, длина строки 120, форматирование ruff.
+- Документация, комментарии, сообщения об ошибках и вывод CLI — на русском языке.
+- SPDX-заголовки обязательны в каждом файле:
+
+```python
+# SPDX-FileCopyrightText: 2026 Ваше Имя
+# SPDX-License-Identifier: Apache-2.0
+```
+
+Файлы, унаследованные от исходного проекта sbom-checker, сохраняют строку копирайта ИСП РАН — не удаляйте её, добавляйте свою следом.
+
+- Комментарии объясняют «почему», а не «что». Комментарий, пересказывающий соседнюю строку кода, не нужен.
+
+## Структура проекта
+
+CLI построен на typer: `efs/cli.py` — единственная точка входа, она разбирает аргументы и передаёт их в `run(args)` соответствующего модуля. Логика команд живёт в модулях (`checker.py`, `updater.py`, `postprocess.py`, ...), в CLI её быть не должно.
+
+Документация лежит в [`docs/`](docs/): [руководство по ФСТЭК](docs/fstec.md), [справочник команд](docs/commands.md), [описание конфига](docs/config.md). Меняете поведение команды — поправьте справочник в том же коммите.
+
+## Коммиты и pull request'ы
+
+- Заголовок коммита — одной строкой, на английском, в формате Conventional Commits: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`, `ci:`, `build:`, `style:`.
+- Ломающие изменения помечаются восклицательным знаком: `refactor!: ...`.
+- Одно изменение — один коммит. Форматирование не смешивается с содержательными правками.
+- Изменения, заметные пользователю, добавляются в `CHANGELOG.md` в раздел `Unreleased`.
+
+## Релизы
+
+Версия задаётся в `pyproject.toml`. Релиз выпускается тегом:
+
+```bash
+git tag v1.1.0
+git push origin v1.1.0
+```
+
+Дальше всё делает workflow `release.yml`: собирает дистрибутивы, публикует их в PyPI через trusted publishing и создаёт релиз на GitHub. Токены PyPI в секретах репозитория не хранятся.
+
+## Лицензия
+
+Отправляя pull request, вы соглашаетесь на распространение своего вклада на условиях [Apache License 2.0](LICENSE).