Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 93 additions & 67 deletions .github/workflows/build-ubuntu20.yml
Original file line number Diff line number Diff line change
@@ -1,85 +1,111 @@
name: Build Ubuntu 20.04 binaries

# Triggered manually for binary releases; see OPEN_SOURCE_AUDIT.md.

on:
workflow_dispatch:
inputs:
ref:
description: Git ref to build
description: Existing annotated vX.Y.Z tag from the selected Forge line
required: true
default: v2.0.1
type: string
version:
description: Release version without the v prefix
description: Exact node version in the tag and source manifest (not the Forge line)
required: true
default: 2.0.1

type: string
release_line:
description: Forge compatibility line
required: true
type: choice
options:
- 1.x
- 2.x
default: 2.x
workflow_call:
inputs:
ref:
description: Existing annotated vX.Y.Z tag from the selected Forge line
required: true
type: string
version:
description: Exact node version in the tag and source manifest (not the Forge line)
required: true
type: string
release_line:
description: Forge compatibility line
required: true
type: string
permissions:
contents: read

jobs:
build:
runs-on: ubuntu-latest
container:
image: ubuntu:20.04
env:
RELEASE_VERSION: ${{ inputs.version }}
RELEASE_TAG: ${{ inputs.ref }}
RELEASE_LINE: ${{ inputs.release_line }}
steps:
- name: Install system tools
run: |
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y \
binutils \
ca-certificates \
curl \
file \
git
rm -rf /var/lib/apt/lists/*

- uses: actions/checkout@v6
with:
ref: ${{ inputs.ref }}

- name: Install uv and Python 3.12
run: |
curl -LsSf https://astral.sh/uv/0.12.5/install.sh |
env UV_INSTALL_DIR=/usr/local/bin sh
uv python install 3.12
uv --version
uv run --no-project --python 3.12 python --version

- name: Build with PyInstaller
run: ./scripts/build_pyinstaller.sh

- name: Verify and package binaries
run: |
test "${{ inputs.ref }}" = "v${RELEASE_VERSION}"
./dist/joint_trajectory_controller --help >/dev/null
./dist/gripper_action_controller --help >/dev/null
./dist/fake_joint_plant --help >/dev/null
file ./dist/joint_trajectory_controller ./dist/gripper_action_controller ./dist/fake_joint_plant
ldd --version | sed -n '1p'
archive="forge-controls-v${RELEASE_VERSION}-ubuntu20.04-x86_64.tar.gz"
tar \
--sort=name \
--mtime='UTC 1970-01-01' \
--owner=0 \
--group=0 \
--numeric-owner \
-C dist \
-czf "${archive}" \
joint_trajectory_controller \
gripper_action_controller \
fake_joint_plant
sha256sum "${archive}" > "${archive}.sha256"
tar -tzf "${archive}"
sha256sum --check "${archive}.sha256"

- uses: actions/upload-artifact@v6
with:
name: forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64
path: |
forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64.tar.gz
forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64.tar.gz.sha256
if-no-files-found: error
retention-days: 30
- name: Install system tools
run: |
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y \
binutils \
ca-certificates \
curl \
file \
git
rm -rf /var/lib/apt/lists/*
- uses: actions/checkout@v6
with:
ref: refs/tags/${{ inputs.ref }}
fetch-depth: 0
persist-credentials: false
- name: Check out release tooling from the workflow commit
uses: actions/checkout@v6
with:
ref: ${{ github.workflow_sha }}
path: .release-tools
persist-credentials: false
- name: Install uv and Python 3.12
run: |
curl -LsSf https://astral.sh/uv/0.12.5/install.sh |
env UV_INSTALL_DIR=/usr/local/bin sh
uv python install 3.12
uv --version
uv run --no-project --python 3.12 python --version
- name: Validate Forge release line and source version
run: |
git config --global --add safe.directory "$(pwd -P)"
uv run --no-project --python 3.12 python .release-tools/scripts/check_release_line.py --line "$RELEASE_LINE" --tag "$RELEASE_TAG" --version "$RELEASE_VERSION" --default-branch main
- name: Build with PyInstaller
run: ./scripts/build_pyinstaller.sh
- name: Verify and package binaries
run: |
test "${RELEASE_TAG}" = "v${RELEASE_VERSION}"
./dist/joint_trajectory_controller --help >/dev/null
./dist/gripper_action_controller --help >/dev/null
./dist/fake_joint_plant --help >/dev/null
file ./dist/joint_trajectory_controller ./dist/gripper_action_controller ./dist/fake_joint_plant
ldd --version | sed -n '1p'
archive="forge-controls-v${RELEASE_VERSION}-ubuntu20.04-x86_64.tar.gz"
tar \
--sort=name \
--mtime='UTC 1970-01-01' \
--owner=0 \
--group=0 \
--numeric-owner \
-C dist \
-czf "${archive}" \
joint_trajectory_controller \
gripper_action_controller \
fake_joint_plant
sha256sum "${archive}" > "${archive}.sha256"
tar -tzf "${archive}"
sha256sum --check "${archive}.sha256"
- uses: actions/upload-artifact@v6
with:
name: forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64
path: |
forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64.tar.gz
forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64.tar.gz.sha256
if-no-files-found: error
retention-days: 30
24 changes: 24 additions & 0 deletions .github/workflows/release-checks.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
name: Release line checks
on:
pull_request:
paths:
- '.github/workflows/**'
- 'scripts/check_release_line.py'
- 'scripts/test_release_line.py'
push:
paths:
- '.github/workflows/**'
- 'scripts/check_release_line.py'
- 'scripts/test_release_line.py'
permissions:
contents: read
jobs:
release-line-checks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with:
python-version: '3.12'
- name: Test source selection, versions and Forge/Dora compatibility
run: python -m unittest discover -s scripts -p test_release_line.py -v
131 changes: 131 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
name: Build versioned release

on:
workflow_dispatch:
inputs:
release_line:
description: Forge compatibility line (independent of the node version)
type: choice
options: [1.x, 2.x]
default: 2.x
required: true
tag:
description: Existing annotated vX.Y.Z tag on the selected release line
type: string
required: true
build_binaries:
description: Include the existing Ubuntu binary build where available
type: boolean
default: false

permissions:
contents: read

concurrency:
group: release-${{ inputs.tag }}
cancel-in-progress: false

jobs:
packages:
runs-on: ubuntu-latest
outputs:
version: ${{ steps.release.outputs.version }}
steps:
- uses: actions/checkout@v6
with:
ref: refs/tags/${{ inputs.tag }}
fetch-depth: 0
persist-credentials: false
- name: Check out release tooling from the workflow commit
uses: actions/checkout@v6
with:
ref: ${{ github.workflow_sha }}
path: .release-tools
persist-credentials: false
- uses: actions/setup-python@v6
with:
python-version: '3.12'
- name: Validate release line and immutable source
id: release
env:
RELEASE_LINE: ${{ inputs.release_line }}
RELEASE_TAG: ${{ inputs.tag }}
run: >-
python .release-tools/scripts/check_release_line.py
--line "$RELEASE_LINE" --tag "$RELEASE_TAG"
--default-branch main
- name: Build source archive and Python distributions when supported
env:
RELEASE_TAG: ${{ inputs.tag }}
RELEASE_LINE: ${{ inputs.release_line }}
PACKAGE_KIND: ${{ steps.release.outputs.package_kind }}
run: |
set -euo pipefail
mkdir -p release-assets
name="${GITHUB_REPOSITORY#*/}"
git archive --format=tar.gz --prefix="${name}-${RELEASE_TAG}/" \
--output="release-assets/${name}-forge-${RELEASE_LINE}-${RELEASE_TAG}-source.tar.gz" HEAD
if [ "$PACKAGE_KIND" = python ]; then
python -m pip install uv==0.13.7
uv build --no-sources --out-dir release-assets
python -m pip install twine==7.0.0
python -m twine check release-assets/*.whl release-assets/*[0-9].tar.gz
fi
python .release-tools/scripts/check_release_line.py \
--line "$RELEASE_LINE" --tag "$RELEASE_TAG" \
--default-branch main > release-assets/release-metadata.json
(cd release-assets && sha256sum ./* > source-SHA256SUMS.txt)
- uses: actions/upload-artifact@v6
with:
name: release-source-${{ inputs.release_line }}-${{ inputs.tag }}
path: release-assets/*
if-no-files-found: error

binaries:
needs: packages
if: ${{ inputs.build_binaries }}
permissions:
contents: read
uses: ./.github/workflows/build-ubuntu20.yml
with:
ref: ${{ inputs.tag }}
version: ${{ needs.packages.outputs.version }}
release_line: ${{ inputs.release_line }}

draft:
needs: [packages, binaries]
if: ${{ always() && needs.packages.result == 'success' && (needs.binaries.result == 'success' || needs.binaries.result == 'skipped') }}
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/download-artifact@v6
with:
path: release-assets
merge-multiple: true
- name: Verify assets and attach to a draft without replacing published files
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
RELEASE_TAG: ${{ inputs.tag }}
RELEASE_LINE: ${{ inputs.release_line }}
run: |
set -euo pipefail
cd release-assets
sha256sum --check source-SHA256SUMS.txt
for checksum in ./*.sha256; do
[ -e "$checksum" ] || continue
sha256sum --check "$checksum"
done
if gh release view "$RELEASE_TAG" --json isDraft --jq .isDraft > /tmp/release-draft-state 2>/tmp/release-lookup-error; then
test "$(cat /tmp/release-draft-state)" = true
elif grep -qi 'release not found' /tmp/release-lookup-error; then
printf 'Forge %s release candidate from %s.\n\nUse peers and Dora from the same compatibility line. Build success does not establish hardware, model, sustained-run or rollback acceptance. Review the workflow results before publishing.\n' \
"$RELEASE_LINE" "$RELEASE_TAG" > /tmp/release-notes
gh release create "$RELEASE_TAG" --verify-tag --draft --latest=false \
--title "$RELEASE_TAG (Forge $RELEASE_LINE)" --notes-file /tmp/release-notes
else
cat /tmp/release-lookup-error >&2
exit 1
fi
gh release upload "$RELEASE_TAG" ./*
27 changes: 27 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,30 @@ Review the complete bundled artifact before publishing standalone executables.
This branch prepares node version `2.0.0` for Dora 1.x, frozen to Dora `1.0.1` for migration validation. It uses the official Forge 2.x distributions; Common is at least `2.1.0`. Regenerated locks and all executable entrypoints are part of the change.

Every change report must list repository, changes and test evidence, including per-node `dora run` records and a chained test containing `adapter-forge-gateway`. Unavailable hardware/model checks remain pending. Source PRs do not publish stable releases or synchronize GitLab; synchronization follows full acceptance.

## Versioned releases

**Mandatory tag-first release rule:** merge the version/lock change, create an annotated version tag on that reviewed commit, build that exact tag, validate the artifacts, then publish. Moving branch names, untagged commit IDs and replacement of published tags are not release inputs.

| Release line | Source | Node/package version | Runtime |
| --- | --- | --- | --- |
| Forge 1.x | `stable/1.x` | `1.x`, tag `v1.X.Y` | Forge 1.x / Dora 0.4.x |
| Forge 2.x | `main` | `2.x`, tag `v2.X.Y` | Forge 2.x / Dora 1.x |

**Legacy normalization:** nodes previously at 0.x on `stable/1.x` release as **1.0.0**, retaining Forge 1.x / Dora 0.4.x dependencies and runtime behavior. Existing 1.x package versions are retained. Node/package majors now follow the Forge compatibility line; a 0.x tag is rejected.

Run **Build versioned release** from `main` for either line. First merge the version/lock changes into the selected source branch, then create an unused **annotated** tag on that reviewed commit. The tag must match package metadata. Never move existing tags or reuse a published version. Dispatch uses the workflow's reviewed tooling with the exact tagged source, so legacy tags need not contain the new release helper.

```bash
# Replace with an existing, reviewed and unpublished tag matching source metadata.
TAG=v1.X.Y
gh workflow run release.yml --ref main -f release_line=1.x -f tag="$TAG"
TAG=v2.X.Y
gh workflow run release.yml --ref main -f release_line=2.x -f tag="$TAG"
```

The workflow verifies tag type, source commit, branch ancestry, source version and locked Forge/Dora compatibility. It builds source archives and wheel/sdist where supported, checks Python distribution metadata and SHA-256, and creates or attaches to a **draft GitHub Release**. Published releases/assets are not overwritten; review all build results and acceptance evidence before publishing. This workflow does not publish node packages to PyPI.

Set `build_binaries=true` to call the existing Ubuntu 20.04 binary workflow; its existing architecture, CLI and archive checks remain in force. You can also run `build-ubuntu20.yml` directly with `ref`, `version` and `release_line`; `ref` must be an annotated tag, not a moving branch. Binary artifacts are attached only after all selected jobs succeed.

The source archive preserves the tagged tree; external SDKs/submodules, model downloads and site configuration remain separate prerequisites. A dependency or SDK build failure is not successful release acceptance. Build success does not establish single-node or Gateway-chain `dora run`, hardware, real-model, sustained-run or rollback acceptance. Every acceptance chain must include `adapter-forge-gateway` from the same compatibility line. Forge 2.x is a **breaking change**: align Forge libraries, node versions and Dora across the entire deployment; keep 1.x on its maintenance branch.
27 changes: 27 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,30 @@
本分支准备节点版本 `2.0.0`,适配 Dora 1.x,迁移验证锁定 Dora `1.0.1`。使用正式 Forge 2.x 分发包;Common 至少为 `2.1.0`。此次更新包括依赖锁文件与各独立可执行入口。

每轮报告必须列出仓库、改动和测试证据,包括各节点的 `dora run` 记录,以及包含 `adapter-forge-gateway` 的串联测试。缺少硬件或模型的验收项保持待验证。源码 PR 不等于正式发布;整体验收通过后再同步 GitLab。

## 分版本发布

**发布规则(强制):** 合并版本/锁文件修改 → 在已审查提交上创建 annotated 版本标签 → 从该标签精确构建 → 校验产物 → 发布。禁止使用移动分支、未打标签的提交构建 Release,禁止覆盖已发布标签。

| 维护线 | 源码 | 节点/包版本 | 运行时 |
| --- | --- | --- | --- |
| Forge 1.x | `stable/1.x` | `1.x`,标签 `v1.X.Y` | Forge 1.x / Dora 0.4.x |
| Forge 2.x | `main` | `2.x`,标签 `v2.X.Y` | Forge 2.x / Dora 1.x |

**旧版版本号统一:** `stable/1.x` 原为 0.x 的节点以 **1.0.0** 发布,保留 Forge 1.x / Dora 0.4.x 依赖与运行行为。已有 1.x 版本保留。节点/包主版本与 Forge 兼容线一致,不再接受 0.x 发布标签。

两条线均从 `main` 运行 **Build versioned release**。先将版本和锁文件修改通过 PR 合并至对应源码分支,再在已审查提交上创建未占用的 **annotated** 标签,标签必须匹配包元数据。禁止移动已有标签或复用已发布版本。工作流使用自身已审查的发布工具与精确标签源码,旧标签无需包含新发布脚本。

```bash
# 替换为已存在、已审查、未发布且与源码元数据一致的标签。
TAG=v1.X.Y
gh workflow run release.yml --ref main -f release_line=1.x -f tag="$TAG"
TAG=v2.X.Y
gh workflow run release.yml --ref main -f release_line=2.x -f tag="$TAG"
```

流水线校验标签类型、源码提交、分支归属、源码版本及锁定的 Forge/Dora 兼容性;构建源码归档及项目支持的 wheel/sdist,检查 Python 分发元数据与 SHA-256,并创建或附加至 **GitHub Release 草稿**。不覆盖已发布 Release 或产物;发布前检查全部构建结果与验收依据。该流程不发布节点包至 PyPI。

设置 `build_binaries=true` 复用已有 Ubuntu 20.04 二进制工作流,保留原架构、CLI 和归档校验。也可直接运行 `build-ubuntu20.yml`,传入 `ref`、`version`、`release_line`;`ref` 必须为 annotated 标签,不能为移动分支。仅在所有选定任务通过后附加二进制产物。

源码归档保留标签中的文件;外部 SDK/submodule、模型下载与现场配置仍是独立前置条件。依赖或 SDK 构建失败不能视为发布验收通过。构建成功不代表单节点或串联 `dora run`、真机、真实模型、长稳态或回滚验收通过;每条验收链必须包含相同兼容线的 `adapter-forge-gateway`。Forge 2.x 属于 **breaking change**,整个部署的 Forge 库、节点版本与 Dora 必须对齐;1.x 保留在维护分支。
Loading