From f7b28a13913b2177b44ca5b5e434c3c404ec2bcf Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 15:48:25 +0300 Subject: [PATCH] docs: add Russian documentation --- .github/RELEASE_POLICY.md | 2 ++ .github/RELEASE_POLICY.ru.md | 23 ++++++++++++++++ ACTIONS_PINS.md | 2 ++ ACTIONS_PINS.ru.md | 27 +++++++++++++++++++ AGENTS.md | 2 ++ AGENTS.ru.md | 36 +++++++++++++++++++++++++ RELEASE_PLATFORM.md | 2 ++ RELEASE_PLATFORM.ru.md | 51 ++++++++++++++++++++++++++++++++++++ RELEASE_RECOVERY.md | 2 ++ RELEASE_RECOVERY.ru.md | 47 +++++++++++++++++++++++++++++++++ SECURITY.md | 2 ++ SECURITY.ru.md | 11 ++++++++ 12 files changed, 207 insertions(+) create mode 100644 .github/RELEASE_POLICY.ru.md create mode 100644 ACTIONS_PINS.ru.md create mode 100644 AGENTS.ru.md create mode 100644 RELEASE_PLATFORM.ru.md create mode 100644 RELEASE_RECOVERY.ru.md create mode 100644 SECURITY.ru.md diff --git a/.github/RELEASE_POLICY.md b/.github/RELEASE_POLICY.md index a9e8377..9c07ed4 100644 --- a/.github/RELEASE_POLICY.md +++ b/.github/RELEASE_POLICY.md @@ -1,5 +1,7 @@ # 4FusionLab — automatic runtime release policy +[Русская версия](RELEASE_POLICY.ru.md) + ## Trigger - A direct push to `main` or a PR merge into `main` is the only normal release event. PR checks, manual CI dispatch and version-tag pushes **do not** initiate publication. diff --git a/.github/RELEASE_POLICY.ru.md b/.github/RELEASE_POLICY.ru.md new file mode 100644 index 0000000..566d8a0 --- /dev/null +++ b/.github/RELEASE_POLICY.ru.md @@ -0,0 +1,23 @@ +# 4FusionLab — политика автоматических релизов исполняемых компонентов + +[English](RELEASE_POLICY.md) + +## Запуск + +- Прямой push в `main` или объединение PR в `main` — единственное обычное событие релиза. Проверки PR, ручной запуск CI и отправка тегов версий **не** запускают публикацию. +- Перед публикацией сравнивайте весь диапазон `github.event.before..GITHUB_SHA`, включая переименованные и удалённые исполняемые файлы. Релиз допустим **только**, если отправленные коммиты изменяют поставляемый файл аддона или исполняемой среды, ресурс, нативный компонент либо явно назначенный вход дистрибутива. +- Репозитории с поставляемыми исполняемыми компонентами используют `.github/release-paths.txt` как проверенный перечень, контролируемый `scripts/release_changes.py`. В репозиториях без исполняемых компонентов нет задания релиза. Изменения только README, руководств, проектной документации, скриншотов, тестов, CI, политики репозитория или конфигурации GitVersion не должны публиковать релиз. +- До публикации должны успешно завершиться все обязательные существующие проверки CI. При отказе проверки не создаётся релиз, не изменяется тег и не заменяются артефакты. + +## Версия и распространение + +- GitVersion.Tool **6.8.2** определяет числовую версию `MAJOR.MINOR.PATCH` с помощью `GitVersion.yml` и полной истории Git. ZIP пакета, встроенный манифест Fusion (где применимо), автоматически созданный неизменяемый тег `vMAJOR.MINOR.PATCH` и GitHub Release относятся к одному коммиту и версии. +- Конвейер создаёт тег **автоматически** при публикации GitHub Release. Участники никогда не создают и не отправляют теги релизов вручную. Существующий тег версии, указывающий на другой коммит, считается ошибкой; опубликованный релиз никогда не перезаписывается. +- При наличии используются проверенные заметки конкретной версии; иначе заметки автоматически создаются из истории Git. Подготовка файла заметок вручную только для выпуска изменения кода не требуется. +- Стабильные релизы становятся Latest. Предварительные выпуски никогда не становятся Latest. Продолжают действовать проектные ограничения приёмки CAD, тестирования, подписанных архивов и контрольных сумм, совместимости ОС и публикации. + +## Этот репозиторий + +Этот репозиторий содержит только профиль и метаданные организации 4FusionLab. В нём нет аддона Fusion или распространяемого исполняемого компонента, а значит и GitHub Release. + +Если push не меняет подходящие исполняемые файлы, CI может запуститься, но задание GitHub Release пропускается, даже если GitVersion вычисляет другую версию-кандидат. diff --git a/ACTIONS_PINS.md b/ACTIONS_PINS.md index 5c665ec..b7dd828 100644 --- a/ACTIONS_PINS.md +++ b/ACTIONS_PINS.md @@ -1,5 +1,7 @@ # Official GitHub Actions pins +[Русская версия](ACTIONS_PINS.ru.md) + This file is the 4FusionLab source of truth for first-party GitHub Actions used in CI, add-in packaging and (manual) GitHub Pages publishing. Check the upstream repository tag ref before changing any SHA. Pin to an immutable **40-character commit SHA**, not `@vN`, `@main` or an abbreviated hash. | Action | Reviewed version | Immutable commit SHA | diff --git a/ACTIONS_PINS.ru.md b/ACTIONS_PINS.ru.md new file mode 100644 index 0000000..985cbdf --- /dev/null +++ b/ACTIONS_PINS.ru.md @@ -0,0 +1,27 @@ +# Закреплённые версии официальных GitHub Actions + +[English](ACTIONS_PINS.md) + +Этот файл — источник истины 4FusionLab для официальных GitHub Actions, используемых в CI, упаковке аддонов и ручной публикации GitHub Pages. Перед изменением SHA проверяйте ссылку на тег в исходном репозитории. Закрепляйте неизменяемый **полный SHA коммита из 40 символов**, а не `@vN`, `@main` или сокращённый хеш. + +| Action | Проверенная версия | Неизменяемый SHA коммита | +| --- | --- | --- | +| `actions/checkout` | `v7.0.1` | `3d3c42e5aac5ba805825da76410c181273ba90b1` | +| `actions/setup-python` | `v7.1.0` | `6d4fd22b20465ccc0f7354476588e8df7c9ca0e0` | +| `actions/setup-node` | `v6` | `249970729cb0ef3589644e2896645e5dc5ba9c38` | +| `actions/upload-artifact` | `v7.0.2` | `cf430e030ddbb5b0abf93d22962f4752f3646cd9` | +| `actions/download-artifact` | `v8.0.2` | `9000827ccba6bdab643e8b6fd33ac0654aef8333` | +| `actions/configure-pages` | `v5` | `983d7736d9b0ae728b81ab479565c72886d7745b` | +| `actions/upload-pages-artifact` | `v3` | `56afc609e74202658d3ffba0e8f6dda462b719fa` | +| `actions/deploy-pages` | `v4` | `d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e` | + +Проверено **2026-11-07** по каждому вышестоящему `refs/tags/` через GitHub REST API. Документ намеренно **не** утверждает, что эти версии навсегда останутся последними. + +## Правила сопровождения + +1. Сохраняйте существующую архитектуру и CI продукта для каждой ОС. Обновление официального Action относится только к инфраструктуре и само по себе **не должно** менять `.github/release-paths.txt` или публиковать GitHub Release. +2. По возможности обновляйте Actions вместе, создавая один удобный для проверки PR на репозиторий. Перед объединением проверяйте фактический CI PR, включая требования к ZIP и SHA-256; затем проверяйте запуски `main` и пропущенные шаги публикации. +3. Разрешение `contents: write` нужно только заданиям релиза продукта. Для обычного CI оставляйте `contents: read`; при checkout задавайте `persist-credentials: false`, кроме случаев, когда конкретная разрешённая запись требует другого. +4. Не развёртывайте автоматически демо Filamentra-DataSource в GitHub Pages при обновлении закреплённых версий. Его workflow намеренно запускается вручную. +5. Общие составные Actions 4FusionLab поддерживаются отдельно: потребители закрепляют `4FusionLab/.github/.github/actions/*` за проверенным SHA коммита платформы. GitVersion.Tool остаётся версии `6.8.2`. +6. При изменении закрепления определите тег в исходном GitHub-репозитории, изучите несовместимые изменения, обновите эту таблицу и PR потребителей и сохраняйте комментарии с версиями рядом с закреплёнными строками `uses:`. diff --git a/AGENTS.md b/AGENTS.md index deafa31..2e8fa6c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # 4FusionLab engineering instructions +[Русская версия](AGENTS.ru.md) + This repository holds reusable, **read-only** CI building blocks and organization-level defaults. Product-specific instructions belong in each product repository. ## Language and product documentation diff --git a/AGENTS.ru.md b/AGENTS.ru.md new file mode 100644 index 0000000..ad54de4 --- /dev/null +++ b/AGENTS.ru.md @@ -0,0 +1,36 @@ +# Инженерные инструкции 4FusionLab + +[English](AGENTS.md) + +Этот репозиторий содержит переиспользуемые компоненты CI **только для чтения** и общие настройки организации. Инструкции конкретного продукта находятся в его репозитории. + +## Язык и документация продуктов + +- При создании или изменении README продукта следуйте [правилам README](README_GUIDELINES.ru.md), включая соответствие языковых версий и проверку лицензии. +- Документы ведутся на английском; для документации поддерживаются отдельные русские версии. Промежуточные рабочие заметки переводить не требуется. +- Обсуждайте требования и планы на русском. Используйте английский для подписей интерфейса Autodesk Fusion, стабильных API-идентификаторов и публичных имён входов Actions. +- Сохраняйте раздельную документацию EN/RU, если у продукта уже есть обе версии. Не заменяйте незаметно ни один язык спойлерами или машинными заглушками. +- Соблюдайте существующие архитектуру продукта, условия UX, тесты и оговорки о совместимости CAD. + +## Git, CI и выпуск + +- Для изменений CI и публикации предпочитайте небольшой проверенный PR. Не используйте force-push и не изменяйте опубликованную историю. Сохраняйте возможность прямого push в main, где это разрешено настройками репозитория. +- Не создавайте теги релизов вручную. Push или объединение PR в `main` может опубликовать релиз **только при изменении поставляемых исполняемых файлов после последнего опубликованного Release**. Push только документации может восстановить ранее неудавшийся выпуск, но никогда не должен создавать релиз сам по себе. См. [`RELEASE_RECOVERY.ru.md`](RELEASE_RECOVERY.ru.md). +- Сохраняйте `.github/release-paths.txt` каждого репозитория как проверенный перечень путей, дающих право на релиз. Изменения только README, документации, тестов, workflow, политик и AGENTS.md не должны создавать GitHub Release. +- GitVersion.Tool закреплён за **6.8.2**. Требуется полная история Git. Опубликованные теги, релизы и загруженные артефакты неизменяемы; не переназначайте теги, не перезаписывайте артефакты и не переводите предварительный выпуск в Stable как понижение версии. +- Основные общие Actions находятся в `.github/actions/` и должны закрепляться потребителями за точным SHA коммита. Не используйте движущуюся ветку `main` в рабочих заданиях релиза. +- Закрепляйте официальные `actions/*` за точными проверенными SHA из [`ACTIONS_PINS.ru.md`](ACTIONS_PINS.ru.md). Перед обновлением сверяйте вышестоящие теги; не используйте плавающие теги основных версий в workflow продукта. +- `contents: write` требуется только заданиям публикации; тесты пакета, проверка метаданных и задания PR работают с минимальными правами чтения. +- Успешная автономная сборка или тест Python **не** подтверждает приёмку CAD в Autodesk Fusion. Сохраняйте свидетельства проверок на платформах и условия безопасности и совместимости. + +## Качество + +- Проверяйте общие Actions командой `python -m unittest discover -s .github/tests -v` и workflow проверок общей платформы релизов. +- Для изменения Actions сначала объедините проверенный PR платформы, затем переводите потребителей отдельными PR с успешным CI проекта. Не меняйте исполняемый код продукта в рамках миграции CI. +- Перед заменой команд упаковки продукта проверьте содержимое ZIP, версию манифеста, SHA-256, заметки и различия ОС для этого продукта. +- Никогда не размещайте в этом публичном репозитории учётные данные, секреты, личные CAD-файлы, машинные пути или проприетарные материалы. + +## Совместимость + +- Сохраняйте стабильные UUID манифестов Fusion, идентификаторы команд, названия продуктов, ресурсы платформ, метаданные поддерживаемых ОС и формат установки каждого репозитория. +- `AGENTS.md` на уровне проекта дополняет эти общие ожидания и остаётся основным источником для ограничений API, геометрии и UX конкретного проекта. diff --git a/RELEASE_PLATFORM.md b/RELEASE_PLATFORM.md index a63951b..82e5541 100644 --- a/RELEASE_PLATFORM.md +++ b/RELEASE_PLATFORM.md @@ -1,5 +1,7 @@ # Shared Release Platform +[Русская версия](RELEASE_PLATFORM.ru.md) + Central, reusable Actions for 4FusionLab repositories. Source: [4FusionLab/.github](https://github.com/4FusionLab/.github). ## Compatibility and rollout diff --git a/RELEASE_PLATFORM.ru.md b/RELEASE_PLATFORM.ru.md new file mode 100644 index 0000000..e05b88a --- /dev/null +++ b/RELEASE_PLATFORM.ru.md @@ -0,0 +1,51 @@ +# Общая платформа релизов + +[English](RELEASE_PLATFORM.md) + +Централизованные переиспользуемые Actions для репозиториев 4FusionLab. Источник: [4FusionLab/.github](https://github.com/4FusionLab/.github). + +## Совместимость и внедрение + +| Action | Назначение | Необходимый контекст | +| --- | --- | --- | +| `.github/actions/resolve-version` | GitVersion.Tool **6.8.2**, возвращает числовую версию или SemVer | Полный checkout (`fetch-depth: 0`) | +| `.github/actions/runtime-changes` | Сравнение неопубликованных изменений исполняемых файлов с последним опубликованным ZIP-релизом (по выбору) или исходного диапазона push | Полный checkout, SHA `before` / `after` и `github.token` с правом только на чтение | +| `.github/actions/release-notes` | Использование проверенных заметок версии либо создание из истории | Полный checkout и доступный для записи файл в `runner.temp` | +| `.github/actions/verify-archive` | Проверка ZIP, SHA-256, необязательного манифеста Fusion и непустых заметок | Собранные ZIP-архивы и файлы контрольных сумм | + +**Закрепляйте ссылку на Action за точным SHA объединённого коммита платформы**, а не за `@main` или изменяемым тегом. После успешных тестов платформы открывайте отдельный PR потребителя. + +### Пример проверки права на релиз без записи + +```yaml +- uses: actions/checkout@ + with: + fetch-depth: 0 + persist-credentials: false +- id: changes + uses: 4FusionLab/.github/.github/actions/runtime-changes@ + with: + before: ${{ github.event.before }} + after: ${{ github.sha }} + paths-file: .github/release-paths.txt + recover-unpublished: 'true' + token: ${{ github.token }} +``` + +Продукт публикуется только при `push` в `main` после успешных существующих тестов, сборки, подготовки заметок и проверки архива **и** когда Action runtime-changes возвращает `release=true`. PR и `workflow_dispatch` никогда не публикуют релиз. Push только документации может восстановить ранее **пропущенный** выпуск, но не создаёт релиз, если после последнего опубликованного тега-предка нет неопубликованных поставляемых изменений. Без включения `recover-unpublished` по умолчанию сохраняется исходная проверка диапазона push. + +### Условия безопасности + +- Все составные Actions здесь работают **только на чтение** и не создают теги, GitHub Releases или развёртывания Pages. Финальная публикация GitHub Release остаётся в репозитории продукта с его проверками, правилами каналов и упаковкой. +- Эти Actions не получают разрешение `contents: write`. +- Нельзя перезаписывать ранее опубликованную версию или неизменяемый тег Git, указывающий на другой коммит. +- Изменения тестов, документации и workflows сами по себе не дают права на релиз. Последующий push только документации может повторить выпуск неопубликованных изменений после ошибки CI или публикации. Добавление, удаление и переименование исполняемых файлов остаются основанием для релиза. +- Успешная сборка ZIP в CI не доказывает прохождение нативного интеграционного теста CAD в Fusion. + +Подробнее о поведении при ошибках и миграции — в [RELEASE_RECOVERY.ru.md](RELEASE_RECOVERY.ru.md). Для восстановления релизов **не задавайте фильтр `push.paths`** в основном workflow публикации: он заблокирует повторные запуски при изменении только документации. + +### Модель выполнения + +Репозитории сохраняют существующие матрицы CI для Linux/macOS/Windows, приёмку Fusion, сборщики пакетов и условия публикации. Общие Actions заменяют только дублирующиеся определение версии, фильтрацию путей, создание заметок и проверку архива. + +Для сопровождения платформы добавьте регрессионные тесты в `.github/tests`, добейтесь успешного выполнения `.github/workflows/platform-tests.yml`, объедините изменение в репозиторий платформы, закрепите новый SHA в PR потребителей, проверьте все их проверки и только после этого объединяйте их изменения. diff --git a/RELEASE_RECOVERY.md b/RELEASE_RECOVERY.md index fcdd1d1..f84b4f3 100644 --- a/RELEASE_RECOVERY.md +++ b/RELEASE_RECOVERY.md @@ -1,5 +1,7 @@ # Recovering missed automatic releases +[Русская версия](RELEASE_RECOVERY.ru.md) + ## Problem A push can modify a shippable runtime file while CI or the publishing job fails. diff --git a/RELEASE_RECOVERY.ru.md b/RELEASE_RECOVERY.ru.md new file mode 100644 index 0000000..629654f --- /dev/null +++ b/RELEASE_RECOVERY.ru.md @@ -0,0 +1,47 @@ +# Восстановление пропущенных автоматических релизов + +[English](RELEASE_RECOVERY.md) + +## Проблема + +Push может изменить поставляемый исполняемый файл, но CI или публикация завершатся ошибкой. Следующий push может содержать только изменения README, тестов или workflow; проверка только диапазона `github.event.before..github.sha` пропустит прежнее изменение, пока не изменится другой исполняемый файл. + +## Новый режим по выбору + +При **push в `main`** общий Action `runtime-changes` может запросить GitHub Releases репозитория, определить последний **опубликованный** релиз с ZIP, тег версии которого является предком текущего коммита, и сравнить помеченный тегом коммит с `github.sha` через `git diff --no-renames`. + +- Если накопленная разница содержит подходящие пути исполняемых файлов, выполняются существующие проверки CI и публикации; ручной тег не нужен. +- Если таких путей нет, публикация пропускается, даже если изменились документация или workflow. +- Если опубликованного ZIP-релиза ещё не было, используется **текущий диапазон push**. Это сохраняет прежнее поведение первого релиза. +- Черновики, теги не по формату версии и релизы без ZIP игнорируются. +- Теги и файлы релизов остаются неизменяемыми; не перезаписывайте и не перемещайте их. +- Если GitHub API недоступен, опубликованный тег не найден локально или ни один опубликованный тег не является предком текущего коммита, **завершайте проверку отказом**. Иначе публикация могла бы незаметно пропуститься. +- Push только документации теперь может *повторить ранее пропущенный выпуск*, но сам по себе не создаёт релиз. + +Опубликованный релиз с ZIP используется как историческая контрольная точка. Некоторые старые релизы (например RuEn 1.0.0) не имеют отдельного файла SHA-256. Новые артефакты по-прежнему проверяются существующими проверками ZIP, манифеста и SHA-256 продукта. + +## Workflow потребителя + +Всегда закрепляйте в workflow потребителя **SHA объединённого коммита платформы**. Новый режим намеренно включается отдельно, сохраняя старое поведение для непереведённых проектов. + +```yaml +- name: Detect previously unpublished runtime changes + uses: 4FusionLab/.github/.github/actions/runtime-changes@ + with: + before: ${{ github.event.before }} + after: ${{ github.sha }} + paths-file: .github/release-paths.txt + recover-unpublished: 'true' + token: ${{ github.token }} +``` + +Для задания классификации используйте `permissions: contents: read`, а для checkout — `fetch-depth: 0`; `contents: write` оставляйте только заданию фактической публикации. + +**Критично:** workflow релиза должен запускаться на *каждый push в main*. Фильтр `push.paths` на уровне workflow блокирует восстановление при изменении только документации даже при корректной классификации. По возможности сохраняйте узкие фильтры PR, но удалите фильтры путей push в переведённом workflow релиза. + +## Проверки + +- Тесты платформы охватывают пагинацию и ошибки авторизации GitHub API, вредоносные теги, проверку предков опубликованных релизов, черновики, случай отсутствия релизов и повтор пропущенного выпуска. +- CI PR продукта продолжает проверять полную сборку до релиза. +- После объединения проверяйте оба результата: `Release eligible: true` (есть неопубликованные исполняемые изменения) и `Release eligible: false` (неопубликованных входных файлов нет). +- Никогда не создавайте теги и релизы из PR или вручную запущенного workflow. diff --git a/SECURITY.md b/SECURITY.md index fe46751..63776b5 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,7 @@ # Security policy +[Русская версия](SECURITY.ru.md) + If you believe you have found a security vulnerability in a 4FusionLab repository or release pipeline, **do not post exploitable details in a public GitHub Issue**. Use GitHub's private vulnerability reporting / Security Advisories when enabled for that repository, or contact its maintainers through an existing private communication channel. diff --git a/SECURITY.ru.md b/SECURITY.ru.md new file mode 100644 index 0000000..53b18f1 --- /dev/null +++ b/SECURITY.ru.md @@ -0,0 +1,11 @@ +# Политика безопасности + +[English](SECURITY.md) + +Если вы считаете, что нашли уязвимость в репозитории 4FusionLab или конвейере релизов, **не публикуйте пригодные для эксплуатации подробности в открытом GitHub Issue**. + +Используйте закрытую отправку сообщений об уязвимостях GitHub / Security Advisories, если она включена для репозитория, либо свяжитесь с сопровождающими по существующему частному каналу. + +Полезно указать затронутый аддон и версию, операционные системы, серьёзность и последствия, закрытые шаги воспроизведения и предлагаемый способ устранения. Никогда не включайте в публичные отчёты учётные данные, CAD-документы клиентов, персональные данные и конфиденциальные токены. + +Исправления безопасности тестируются и распространяются в соответствии с той же политикой GitVersion для изменений исполняемых компонентов, что и другие исправления. Правила отдельного продукта могут быть строже.