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
228 changes: 124 additions & 104 deletions .github/workflows/publish-pypi.yml
Original file line number Diff line number Diff line change
@@ -1,137 +1,157 @@
name: Publish Python package to PyPI

on:
workflow_dispatch:
inputs:
tag:
description: "Existing annotated family tag (for example, forge-msgs-v2.1.0); this input does not create a tag"
description: Existing annotated family tag (for example, forge-msgs-v2.1.0); this input does not create a tag
required: true
type: string

release_line:
description: Forge package release line
required: true
type: choice
options:
- 1.x
- 2.x
default: 2.x
publish:
description: Publish verified distributions to PyPI (false builds artifacts only)
required: true
type: boolean
default: false
push:
tags:
- "forge-*-v*"

- forge-*-v*
concurrency:
group: pypi-${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
cancel-in-progress: false

jobs:
resolve:
runs-on: ubuntu-latest
permissions:
contents: read

outputs:
tag: ${{ steps.release.outputs.tag }}
family: ${{ steps.release.outputs.family }}
version: ${{ steps.release.outputs.version }}
distribution: ${{ steps.release.outputs.distribution }}

release_line: ${{ steps.release.outputs.release_line }}
steps:
- name: Resolve and validate release tag
id: release
shell: bash
env:
REQUESTED_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail

if [[ ! "$REQUESTED_TAG" =~ ^forge-(common|msgs|robot|policy|kinematics|tool)-v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
echo "Unsupported release tag: $REQUESTED_TAG" >&2
exit 1
fi

family="${BASH_REMATCH[1]}"
version="${BASH_REMATCH[2]}.${BASH_REMATCH[3]}.${BASH_REMATCH[4]}"

if ! tag_type=$(gh api "repos/${GITHUB_REPOSITORY}/git/ref/tags/${REQUESTED_TAG}" --jq '.object.type'); then
echo "::error::Release tag '${REQUESTED_TAG}' does not exist or cannot be read. Run workflow does not create tags. Create the annotated family tag on the reviewed release commit before retrying." >&2
exit 1
fi
if [[ "$tag_type" != "tag" ]]; then
echo "::error::Release '${REQUESTED_TAG}' must be an annotated tag; a lightweight tag is not supported." >&2
exit 1
fi

echo "tag=$REQUESTED_TAG" >> "$GITHUB_OUTPUT"
echo "family=$family" >> "$GITHUB_OUTPUT"
echo "version=$version" >> "$GITHUB_OUTPUT"
echo "distribution=forge-$family" >> "$GITHUB_OUTPUT"

- name: Resolve and validate release tag
id: release
shell: bash
env:
REQUESTED_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
GH_TOKEN: ${{ github.token }}
SELECTED_LINE: ${{ inputs.release_line }}
run: |
set -euo pipefail

if [[ ! "$REQUESTED_TAG" =~ ^forge-(common|msgs|robot|policy|kinematics|tool)-v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
echo "Unsupported release tag: $REQUESTED_TAG" >&2
exit 1
fi

family="${BASH_REMATCH[1]}"
version="${BASH_REMATCH[2]}.${BASH_REMATCH[3]}.${BASH_REMATCH[4]}"
release_line="${BASH_REMATCH[2]}.x"
if [[ "$release_line" != "1.x" && "$release_line" != "2.x" ]]; then
echo "Only Forge 1.x and 2.x releases are supported" >&2; exit 1
fi
if [[ "$GITHUB_EVENT_NAME" == "workflow_dispatch" && "$SELECTED_LINE" != "$release_line" ]]; then
echo "Selected line differs from the family tag" >&2; exit 1
fi

if ! tag_type=$(gh api "repos/${GITHUB_REPOSITORY}/git/ref/tags/${REQUESTED_TAG}" --jq '.object.type'); then
echo "::error::Release tag '${REQUESTED_TAG}' does not exist or cannot be read. Run workflow does not create tags. Create the annotated family tag on the reviewed release commit before retrying." >&2
exit 1
fi
if [[ "$tag_type" != "tag" ]]; then
echo "::error::Release '${REQUESTED_TAG}' must be an annotated tag; a lightweight tag is not supported." >&2
exit 1
fi

echo "tag=$REQUESTED_TAG" >> "$GITHUB_OUTPUT"
echo "family=$family" >> "$GITHUB_OUTPUT"
echo "version=$version" >> "$GITHUB_OUTPUT"
echo "distribution=forge-$family" >> "$GITHUB_OUTPUT"

echo "release_line=$release_line" >> "$GITHUB_OUTPUT"
publish:
name: Publish ${{ needs.resolve.outputs.tag }}
needs: resolve
runs-on: ubuntu-latest

environment:
name: pypi-${{ needs.resolve.outputs.family }}

permissions:
contents: read
id-token: write

steps:
- name: Check out immutable release tag
uses: actions/checkout@v4
with:
ref: ${{ needs.resolve.outputs.tag }}
fetch-depth: 0

- name: Verify annotated tag and commit
shell: bash
env:
RELEASE_TAG: ${{ needs.resolve.outputs.tag }}
run: |
set -euo pipefail

test "$(git cat-file -t "$RELEASE_TAG")" = "tag"
test "$(git rev-parse "$RELEASE_TAG^{commit}")" = "$(git rev-parse HEAD)"

python scripts/check_release_versions.py \
--tag "$RELEASE_TAG"

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Set up uv
uses: astral-sh/setup-uv@v5
with:
enable-cache: true

- name: Install locked build dependencies
run: |
uv sync --locked --all-packages --all-extras --dev

- name: Build and validate release distributions
shell: bash
env:
CI_COMMIT_TAG: ${{ needs.resolve.outputs.tag }}
RELEASE_FAMILY: ${{ needs.resolve.outputs.family }}
run: |
set -euo pipefail

uv run python scripts/build_python_distributions.py \
--release-family "$RELEASE_FAMILY" \
--out-dir "dist/release/python/$RELEASE_FAMILY"

- name: Upload release artifacts
uses: actions/upload-artifact@v4
with:
name: ${{ needs.resolve.outputs.distribution }}-${{ needs.resolve.outputs.version }}
path: dist/release/python/${{ needs.resolve.outputs.family }}/*
if-no-files-found: error

- name: Publish wheel and source distribution to PyPI
shell: bash
env:
RELEASE_FAMILY: ${{ needs.resolve.outputs.family }}
run: |
set -euo pipefail

uv publish --trusted-publishing always \
"dist/release/python/$RELEASE_FAMILY"/*.whl \
"dist/release/python/$RELEASE_FAMILY"/*.tar.gz
- name: Check out immutable release tag
uses: actions/checkout@v4
with:
ref: ${{ needs.resolve.outputs.tag }}
fetch-depth: 0
persist-credentials: false
- name: Check out release tooling from the workflow commit
uses: actions/checkout@v4
with:
ref: ${{ github.workflow_sha }}
path: .release-tools
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Validate package release line and source branch
env:
RELEASE_TAG: ${{ needs.resolve.outputs.tag }}
RELEASE_LINE: ${{ needs.resolve.outputs.release_line }}
run: python .release-tools/scripts/check_release_line.py --line "$RELEASE_LINE" --tag "$RELEASE_TAG" --default-branch master
- name: Verify annotated tag and commit
shell: bash
env:
RELEASE_TAG: ${{ needs.resolve.outputs.tag }}
run: |
set -euo pipefail

test "$(git cat-file -t "$RELEASE_TAG")" = "tag"
test "$(git rev-parse "$RELEASE_TAG^{commit}")" = "$(git rev-parse HEAD)"

python scripts/check_release_versions.py \
--tag "$RELEASE_TAG"
- name: Set up uv
uses: astral-sh/setup-uv@v5
with:
enable-cache: true
- name: Install locked build dependencies
run: |
uv sync --locked --all-packages --all-extras --dev
- name: Build and validate release distributions
shell: bash
env:
CI_COMMIT_TAG: ${{ needs.resolve.outputs.tag }}
RELEASE_FAMILY: ${{ needs.resolve.outputs.family }}
run: |
set -euo pipefail

uv run python scripts/build_python_distributions.py \
--release-family "$RELEASE_FAMILY" \
--out-dir "dist/release/python/$RELEASE_FAMILY"
- name: Upload release artifacts
uses: actions/upload-artifact@v4
with:
name: ${{ needs.resolve.outputs.distribution }}-${{ needs.resolve.outputs.version }}
path: dist/release/python/${{ needs.resolve.outputs.family }}/*
if-no-files-found: error
- name: Publish wheel and source distribution to PyPI
shell: bash
env:
RELEASE_FAMILY: ${{ needs.resolve.outputs.family }}
run: |
set -euo pipefail

uv publish --trusted-publishing always \
"dist/release/python/$RELEASE_FAMILY"/*.whl \
"dist/release/python/$RELEASE_FAMILY"/*.tar.gz
if: ${{ github.event_name == 'push' || inputs.publish }}
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
21 changes: 21 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -468,3 +468,24 @@ report security issues using the process in `SECURITY.md`.

Forge is licensed under the Apache License, Version 2.0. See `LICENSE` for
details.

## 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 | Package and tag | Runtime compatibility |
| --- | --- | --- | --- |
| Forge 1.x | `stable/1.x` | Family version 1.x, `forge-<family>-v1.X.Y` | Forge 1.x peers / Dora 0.4.x |
| Forge 2.x | `master` | Family version 2.x, `forge-<family>-v2.X.Y` | Forge 2.x peers / Dora 1.x |

Run **Publish Python package to PyPI** from `master` for both lines; the selected existing annotated family tag determines the source. Select `release_line=1.x` or `2.x`. Branch ancestry, tag/source identity, `versions.toml` and family metadata must agree. The workflow never creates or moves tags and does not change package versions.

```bash
# Replace TAG with a new reviewed family tag matching its source metadata.
TAG=forge-msgs-v1.3.2
gh workflow run publish-pypi.yml --ref master -f tag="$TAG" -f release_line=1.x -f publish=false
TAG=forge-msgs-v2.1.1
gh workflow run publish-pypi.yml --ref master -f tag="$TAG" -f release_line=2.x -f publish=false
```

`publish=false` builds and validates wheel/sdist artifacts only. For an intentional PyPI release set `publish=true`; tag-push events retain automatic publishing and derive the line from the family major. Configure the corresponding `pypi-<family>` Trusted Publisher environment before publishing. Published versions and existing tags are immutable. Use an unused patch version for retries requiring changed code. Successful packaging is not node or hardware acceptance. Forge 2.x is a **breaking change**: deploy matching Forge libraries, nodes and Dora together. Rust crate and C++ distribution publication remain separate from this Python workflow.
21 changes: 21 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -412,3 +412,24 @@ flowchart TB
## 许可证

Forge 使用 Apache License 2.0,详见 `LICENSE`。

## 分版本发布

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

| 维护线 | 源码 | 包版本与标签 | 运行时兼容 |
| --- | --- | --- | --- |
| Forge 1.x | `stable/1.x` | 包族 1.x,`forge-<family>-v1.X.Y` | Forge 1.x 对接节点 / Dora 0.4.x |
| Forge 2.x | `master` | 包族 2.x,`forge-<family>-v2.X.Y` | Forge 2.x 对接节点 / Dora 1.x |

两条维护线均从 `master` 运行 **Publish Python package to PyPI**,选择 `release_line=1.x` 或 `2.x`,并指定已存在的 annotated 包族标签。流水线校验分支归属、标签与源码一致性、`versions.toml` 和包族元数据,不创建/移动标签,也不修改包版本。

```bash
# 将 TAG 替换为未发布、已审查且与源码元数据一致的新包族标签。
TAG=forge-msgs-v1.3.2
gh workflow run publish-pypi.yml --ref master -f tag="$TAG" -f release_line=1.x -f publish=false
TAG=forge-msgs-v2.1.1
gh workflow run publish-pypi.yml --ref master -f tag="$TAG" -f release_line=2.x -f publish=false
```

`publish=false` 只构建和检查 wheel/sdist;确需发布 PyPI 时设置 `publish=true`。tag push 保留自动发布,按包族主版本确定维护线。发布前需配置对应 `pypi-<family>` Trusted Publisher 环境。已发布版本和现有标签不可覆盖;修改源码后重试需使用未占用的新补丁版本。打包成功不等于节点或硬件验收。Forge 2.x 属于 **breaking change**,库、节点和 Dora 必须对齐部署。Rust crate 和 C++ 发布独立于此 Python 工作流。
62 changes: 62 additions & 0 deletions migration/release-lines-report.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
{
"repository": "PhyAgentOS/forge",
"target": "master",
"scope": "Build and document Forge 1.x and 2.x releases",
"release_line_unit_tests": {
"command": "python -m unittest discover -s scripts -p test_release_line.py -v",
"passed": 12
},
"workflow_validation": {
"tool": "actionlint 1.7.12",
"result": "passed"
},
"distribution_checks": {
"result": "source-only project or separately checked core package families",
"artifacts": []
},
"source_profile_scope": "Local candidate worktrees; proposed maintenance changes are not deployed or merged yet. Full checksums and raw logs remain in the local workspace.",
"source_profiles": [
{
"repo": "PhyAgentOS/forge",
"line": "1.x",
"version": "1.3.1",
"forge_majors": [
1
],
"dora_versions": [],
"kind": "family",
"ready": true
},
{
"repo": "PhyAgentOS/forge",
"line": "2.x",
"version": "2.1.0",
"forge_majors": [
2
],
"dora_versions": [],
"kind": "family",
"ready": true
}
],
"dora_run": {
"single_node": {
"status": "not-run",
"reason": "This change verifies release tooling and version metadata; no current node runtime acceptance is claimed."
},
"gateway_chain": {
"status": "not-run",
"reason": "Fresh integration acceptance remains required; every such chain must include adapter-forge-gateway from the same Forge line."
}
},
"linux_binary_release_build": "not-run in this change; existing binary workflow checks are preserved",
"hardware_model_sustained_rollback_acceptance": "pending",
"published_tags_releases_modified": false,
"gitlab_sync": false,
"core_checks": {
"family_version_validators": "passed on both 1.x and 2.x",
"wheel_sdist_family_pairs": 12,
"twine_check": "passed",
"release_resolver_cases_passed": 15
}
}
Loading
Loading