SharpEmu 版本发布指南基于 scripts/release.py 的 prepare / tag 双阶段发布流程【免费下载链接】sharpemuAn experimental PlayStation 5 emulator for Windows, Linux and macOS.项目地址: https://gitcode.com/GitHub_Trending/sh/sharpemuSharpEmu 的版本发布不是靠手工改版本号、手工打 Tag 完成的而是由一个专用的 Python 发布脚本 scripts/release.py 统一驱动先用prepare子命令把版本号提升通过 Pull Request 合入main再用tag子命令在合并后的main上创建并推送带v前缀的注释标签从而自动触发 GitHub Release 工作流。本文完整拆解这两个阶段的操作步骤、版本号格式约束并结合脚本源码说明每一步背后的校验逻辑与底层实现帮助你安全、可重复地发布 SharpEmu 的新版本。一、发布管线概览为什么是两阶段SharpEmu 的发布流程设计为两个独立的、必须按顺序执行的步骤详见 docs/release-use.mdPrepare准备以main为基线创建release/版本号分支把SharpEmuVersion提升到目标版本并提交、推送然后通过 Pull Request 将该版本号变更合入main。Tag发布在版本号提升 PR 合并之后回到main由脚本核验Directory.Build.props中的版本号与请求一致创建注释标签v版本号并推送到远程仓库。推送到远程的 Tag 会自动触发GitHub Release 工作流进而产出正式发布的构建产物。这种先合版本号、后打标签的次序保证了任何发布标签都指向一个确实携带了对应版本号的提交杜绝了标签已打、版本号没改的错位状态。脚本对两个命令的定位也有清晰区分prepare只负责制造一次版本号提升变更并通过 PR 审查流程合入主干tag才真正对外宣告发布。这也是脚本在prepare成功后会提示你After merging the PR, run:python scripts/release.py tag version的原因。二、版本号格式约束调用脚本时版本号不能带v前缀v前缀由脚本在创建 Git 标签时自动加上。合法格式示例如下0.0.2 0.0.2-alpha.1 0.0.2-beta.1 0.0.2-beta.2 0.0.2-rc.1脚本在参数解析阶段即做格式校验对应的正则定义在 scripts/release.pyVERSION_PATTERN re.compile(r^\d\.\d\.\d(?:-[0-9A-Za-z.-])?$)即主版本号、次版本号、修订号三段由点分隔的数字是必需的后面可选的预发布后缀如-beta.2只允许由字母、数字、点、连字符组成。任何不符合该模式的输入例如v0.0.2、0.0.2 beta都会在进入正式流程前被parser.error(...)直接拒绝错误信息会提示版本应形如0.0.2、0.0.2-beta.2或0.0.2-rc.1。当前仓库的版本由 Directory.Build.props 中的属性统一承载SharpEmuVersion0.0.3-release.3/SharpEmuVersion Version$(SharpEmuVersion)/Version其中Version直接引用SharpEmuVersion这意味着该值同时决定了 NuGet/程序集版本语义发布脚本只需保证SharpEmuVersion这一处被正确更新整个项目的版本号就随之同步。三、阶段一prepare —— 准备版本号提升在干净的main分支上执行python scripts/release.py prepare 0.0.2-beta.23.1 脚本按顺序完成的工作对照 prepare_release 实现该命令依次执行校验工作区干净通过git status --porcelain检查是否有未提交的改动任一改动都会中止流程见ensure_clean_worktree。确认当前分支为main通过git branch --show-current获取当前分支若处于 detached HEAD 或非main分支直接报错见get_current_branch。更新本地main执行git pull --ff-only remote main确保以最新的远端主干为基线。检查分支是否已存在分别用git branch --list本地和git ls-remote --heads remote branch远程确认release/0.0.2-beta.2尚未存在避免覆盖或冲突。读取当前版本号记录Directory.Build.props中现有的SharpEmuVersion用于后续输出旧版本 - 新版本的摘要。创建发布分支执行git switch -c release/0.0.2-beta.2。提升版本号用正则(SharpEmuVersion)([^])(/SharpEmuVersion)精确替换 XML 属性中的值见update_version如果新旧版本相同脚本会拒绝执行。提交版本变更git add后提交提交信息固定为chore: bump version to 0.0.2-beta.2。推送发布分支git push -u remote release/0.0.2-beta.2。3.2 之后提交 Pull Request脚本运行结束后控制台会打印类似下面的指引Prepared release 0.0.1 - 0.0.2-beta.2 Branch pushed: release/0.0.2-beta.2 Open a pull request from: release/0.0.2-beta.2 into: main随后在远端仓库打开 Pull Request将release/0.0.2-beta.2合入main注意只有在 PR 被合并之后才能进入下一步的tag阶段。3.3 可配置参数--remoteprepare与tag都支持--remote参数指定 Git 远程名称默认值为originpython scripts/release.py prepare 0.0.2-beta.2 --remote upstream该远程名会被用于pull --ff-only、ls-remote预检以及最终的push方便贡献者在 fork 或多远程工作流中使用见 参数定义。四、阶段二tag —— 创建并推送发布标签前提版本号提升的 Pull Request已经合并。先更新本地仓库git switch main git pull --ff-only然后执行python scripts/release.py tag 0.0.2-beta.24.1 脚本按顺序完成的工作对照 create_release_tag 实现该命令依次执行校验工作区干净与prepare相同的git status --porcelain检查。确认当前分支为main禁止在其他分支或 detached HEAD 上打发布标签。更新本地maingit pull --ff-only确保包含刚合并的版本号提升提交。核验版本号一致读取 Directory.Build.props 中的SharpEmuVersion必须与命令行传入的版本号完全相等。不一致时脚本报错并同时打印两处版本例如Error: Version mismatch: Directory.Build.props: 0.0.2-beta.1 Requested tag: 0.0.2-beta.2检查标签是否已存在分别用git tag --list本地与git ls-remote --tags远程refs/tags/v...预检避免重复打标签。打印发布说明预览基于git describe --tags --abbrev0 --match v*找到上一个v*标签再用git log --no-merges --reverse --prettytformat:%h %s列出自上一标签以来的非合并提交作为即将生成的 Release Notes 的素材Commits since v0.0.2-beta.1 (12): a1b2c3d chore: bump version to 0.0.2-beta.2 ...创建注释标签执行git tag -a v0.0.2-beta.2 -m SharpEmu 0.0.2-beta.2。推送标签执行git push remote v0.0.2-beta.2并在成功时打印Successfully pushed tag v0.0.2-beta.2.。推送标签后GitHub Release 工作流会自动启动脚本也会提示 The release workflow should start automatically.。4.2 标签触发后的官方构建判定发布标签推送后CI 构建出的产物会携带官方发布身份。构建溯源逻辑位于 src/SharpEmu.Logging/BuildInfo.cs只有同时满足Release 配置、规范仓库sharpemu/sharpemu、触发方式为workflow_dispatch或对main分支的push三个条件时IsOfficialRelease才为真。而编译期注入的这些 CI 元数据CommitSha、Branch、WorkflowRunUrl 等正是由 Directory.Build.props 从GITHUB_*环境变量写入AssemblyMetadata的。这意味着发布流程产生的日志横幅会显示形如SharpEmu a1b2c3d — ...的官方版本标识而本地或 PR 构建则会标注UNOFFICIAL便于用户区分构建来源。五、脚本的工程化细节安全校验与错误处理5.1 统一的 Git 调用封装脚本用run_git封装了所有git子进程调用见 scripts/release.pyGit 不在 PATH 中时抛出ReleaseError(Git was not found in PATH.)任何 Git 命令非零退出时会把 stderr 拼进错误信息一并报告。仓库根目录通过git rev-parse --show-toplevel自动探测见find_repository_root因此脚本无论从仓库哪个子目录调用都能正确定位Directory.Build.props。5.2 版本文件只精确改一处update_version要求SharpEmuVersion在文件中恰好出现一次见 scripts/release.py正则替换计数不等于 1 时报错防止出现多处版本号导致的歧义。写入时强制使用 UTF-8 与 LF 换行保证跨平台下文件内容一致。5.3 错误处理的兜底信息若prepare中途失败例如推送网络错误脚本会在 stderr 打印警告Prepare failed. The release branch may still exist locally.提醒你清理可能残留的本地发布分支后重试。ReleaseError统一以Error: 原因格式输出并返回退出码 1方便在 CI 中直接作为失败信号见 main 入口。六、使用注意事项速查以下是官方文档 docs/release-use.md 与脚本实现共同强调的约束prepare只能从main分支运行脚本会强制校验当前分支。tag只能在版本号提升 PR 合并后运行不要提前打标签。严禁在版本号提升合并之前手工创建发布标签否则会产生版本号与标签错位的发布。两个命令都要求工作区干净git status --porcelain为空未提交改动会直接中止。Directory.Build.props中的SharpEmuVersion必须与tag命令传入的版本号完全一致。版本号一律不带v前缀v由脚本在tag阶段自动添加。七、运行环境说明release.py是纯 Python 3 脚本仅依赖标准库argparse、re、subprocess、sys、pathlib不要求任何第三方包其唯一的外部依赖是git命令行工具且需要具备对远程仓库的推送权限。项目中其他脚本如 scripts/release.py 同目录下的test-linux-docker.sh、validate-synthetic-spirv.sh等各自负责独立的开发流程与发布流程互不干扰。构建本身则由 global.json 锁定的 .NET SDK10.0.103驱动产出位于artifacts目录——发布流程管理的版本号即对应这些构建产物的版本标识。【免费下载链接】sharpemuAn experimental PlayStation 5 emulator for Windows, Linux and macOS.项目地址: https://gitcode.com/GitHub_Trending/sh/sharpemu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SharpEmu 版本发布指南：基于 scripts/release.py 的 prepare / tag 双阶段发布流程
SharpEmu 版本发布指南基于 scripts/release.py 的 prepare / tag 双阶段发布流程【免费下载链接】sharpemuAn experimental PlayStation 5 emulator for Windows, Linux and macOS.项目地址: https://gitcode.com/GitHub_Trending/sh/sharpemuSharpEmu 的版本发布不是靠手工改版本号、手工打 Tag 完成的而是由一个专用的 Python 发布脚本 scripts/release.py 统一驱动先用prepare子命令把版本号提升通过 Pull Request 合入main再用tag子命令在合并后的main上创建并推送带v前缀的注释标签从而自动触发 GitHub Release 工作流。本文完整拆解这两个阶段的操作步骤、版本号格式约束并结合脚本源码说明每一步背后的校验逻辑与底层实现帮助你安全、可重复地发布 SharpEmu 的新版本。一、发布管线概览为什么是两阶段SharpEmu 的发布流程设计为两个独立的、必须按顺序执行的步骤详见 docs/release-use.mdPrepare准备以main为基线创建release/版本号分支把SharpEmuVersion提升到目标版本并提交、推送然后通过 Pull Request 将该版本号变更合入main。Tag发布在版本号提升 PR 合并之后回到main由脚本核验Directory.Build.props中的版本号与请求一致创建注释标签v版本号并推送到远程仓库。推送到远程的 Tag 会自动触发GitHub Release 工作流进而产出正式发布的构建产物。这种先合版本号、后打标签的次序保证了任何发布标签都指向一个确实携带了对应版本号的提交杜绝了标签已打、版本号没改的错位状态。脚本对两个命令的定位也有清晰区分prepare只负责制造一次版本号提升变更并通过 PR 审查流程合入主干tag才真正对外宣告发布。这也是脚本在prepare成功后会提示你After merging the PR, run:python scripts/release.py tag version的原因。二、版本号格式约束调用脚本时版本号不能带v前缀v前缀由脚本在创建 Git 标签时自动加上。合法格式示例如下0.0.2 0.0.2-alpha.1 0.0.2-beta.1 0.0.2-beta.2 0.0.2-rc.1脚本在参数解析阶段即做格式校验对应的正则定义在 scripts/release.pyVERSION_PATTERN re.compile(r^\d\.\d\.\d(?:-[0-9A-Za-z.-])?$)即主版本号、次版本号、修订号三段由点分隔的数字是必需的后面可选的预发布后缀如-beta.2只允许由字母、数字、点、连字符组成。任何不符合该模式的输入例如v0.0.2、0.0.2 beta都会在进入正式流程前被parser.error(...)直接拒绝错误信息会提示版本应形如0.0.2、0.0.2-beta.2或0.0.2-rc.1。当前仓库的版本由 Directory.Build.props 中的属性统一承载SharpEmuVersion0.0.3-release.3/SharpEmuVersion Version$(SharpEmuVersion)/Version其中Version直接引用SharpEmuVersion这意味着该值同时决定了 NuGet/程序集版本语义发布脚本只需保证SharpEmuVersion这一处被正确更新整个项目的版本号就随之同步。三、阶段一prepare —— 准备版本号提升在干净的main分支上执行python scripts/release.py prepare 0.0.2-beta.23.1 脚本按顺序完成的工作对照 prepare_release 实现该命令依次执行校验工作区干净通过git status --porcelain检查是否有未提交的改动任一改动都会中止流程见ensure_clean_worktree。确认当前分支为main通过git branch --show-current获取当前分支若处于 detached HEAD 或非main分支直接报错见get_current_branch。更新本地main执行git pull --ff-only remote main确保以最新的远端主干为基线。检查分支是否已存在分别用git branch --list本地和git ls-remote --heads remote branch远程确认release/0.0.2-beta.2尚未存在避免覆盖或冲突。读取当前版本号记录Directory.Build.props中现有的SharpEmuVersion用于后续输出旧版本 - 新版本的摘要。创建发布分支执行git switch -c release/0.0.2-beta.2。提升版本号用正则(SharpEmuVersion)([^])(/SharpEmuVersion)精确替换 XML 属性中的值见update_version如果新旧版本相同脚本会拒绝执行。提交版本变更git add后提交提交信息固定为chore: bump version to 0.0.2-beta.2。推送发布分支git push -u remote release/0.0.2-beta.2。3.2 之后提交 Pull Request脚本运行结束后控制台会打印类似下面的指引Prepared release 0.0.1 - 0.0.2-beta.2 Branch pushed: release/0.0.2-beta.2 Open a pull request from: release/0.0.2-beta.2 into: main随后在远端仓库打开 Pull Request将release/0.0.2-beta.2合入main注意只有在 PR 被合并之后才能进入下一步的tag阶段。3.3 可配置参数--remoteprepare与tag都支持--remote参数指定 Git 远程名称默认值为originpython scripts/release.py prepare 0.0.2-beta.2 --remote upstream该远程名会被用于pull --ff-only、ls-remote预检以及最终的push方便贡献者在 fork 或多远程工作流中使用见 参数定义。四、阶段二tag —— 创建并推送发布标签前提版本号提升的 Pull Request已经合并。先更新本地仓库git switch main git pull --ff-only然后执行python scripts/release.py tag 0.0.2-beta.24.1 脚本按顺序完成的工作对照 create_release_tag 实现该命令依次执行校验工作区干净与prepare相同的git status --porcelain检查。确认当前分支为main禁止在其他分支或 detached HEAD 上打发布标签。更新本地maingit pull --ff-only确保包含刚合并的版本号提升提交。核验版本号一致读取 Directory.Build.props 中的SharpEmuVersion必须与命令行传入的版本号完全相等。不一致时脚本报错并同时打印两处版本例如Error: Version mismatch: Directory.Build.props: 0.0.2-beta.1 Requested tag: 0.0.2-beta.2检查标签是否已存在分别用git tag --list本地与git ls-remote --tags远程refs/tags/v...预检避免重复打标签。打印发布说明预览基于git describe --tags --abbrev0 --match v*找到上一个v*标签再用git log --no-merges --reverse --prettytformat:%h %s列出自上一标签以来的非合并提交作为即将生成的 Release Notes 的素材Commits since v0.0.2-beta.1 (12): a1b2c3d chore: bump version to 0.0.2-beta.2 ...创建注释标签执行git tag -a v0.0.2-beta.2 -m SharpEmu 0.0.2-beta.2。推送标签执行git push remote v0.0.2-beta.2并在成功时打印Successfully pushed tag v0.0.2-beta.2.。推送标签后GitHub Release 工作流会自动启动脚本也会提示 The release workflow should start automatically.。4.2 标签触发后的官方构建判定发布标签推送后CI 构建出的产物会携带官方发布身份。构建溯源逻辑位于 src/SharpEmu.Logging/BuildInfo.cs只有同时满足Release 配置、规范仓库sharpemu/sharpemu、触发方式为workflow_dispatch或对main分支的push三个条件时IsOfficialRelease才为真。而编译期注入的这些 CI 元数据CommitSha、Branch、WorkflowRunUrl 等正是由 Directory.Build.props 从GITHUB_*环境变量写入AssemblyMetadata的。这意味着发布流程产生的日志横幅会显示形如SharpEmu a1b2c3d — ...的官方版本标识而本地或 PR 构建则会标注UNOFFICIAL便于用户区分构建来源。五、脚本的工程化细节安全校验与错误处理5.1 统一的 Git 调用封装脚本用run_git封装了所有git子进程调用见 scripts/release.pyGit 不在 PATH 中时抛出ReleaseError(Git was not found in PATH.)任何 Git 命令非零退出时会把 stderr 拼进错误信息一并报告。仓库根目录通过git rev-parse --show-toplevel自动探测见find_repository_root因此脚本无论从仓库哪个子目录调用都能正确定位Directory.Build.props。5.2 版本文件只精确改一处update_version要求SharpEmuVersion在文件中恰好出现一次见 scripts/release.py正则替换计数不等于 1 时报错防止出现多处版本号导致的歧义。写入时强制使用 UTF-8 与 LF 换行保证跨平台下文件内容一致。5.3 错误处理的兜底信息若prepare中途失败例如推送网络错误脚本会在 stderr 打印警告Prepare failed. The release branch may still exist locally.提醒你清理可能残留的本地发布分支后重试。ReleaseError统一以Error: 原因格式输出并返回退出码 1方便在 CI 中直接作为失败信号见 main 入口。六、使用注意事项速查以下是官方文档 docs/release-use.md 与脚本实现共同强调的约束prepare只能从main分支运行脚本会强制校验当前分支。tag只能在版本号提升 PR 合并后运行不要提前打标签。严禁在版本号提升合并之前手工创建发布标签否则会产生版本号与标签错位的发布。两个命令都要求工作区干净git status --porcelain为空未提交改动会直接中止。Directory.Build.props中的SharpEmuVersion必须与tag命令传入的版本号完全一致。版本号一律不带v前缀v由脚本在tag阶段自动添加。七、运行环境说明release.py是纯 Python 3 脚本仅依赖标准库argparse、re、subprocess、sys、pathlib不要求任何第三方包其唯一的外部依赖是git命令行工具且需要具备对远程仓库的推送权限。项目中其他脚本如 scripts/release.py 同目录下的test-linux-docker.sh、validate-synthetic-spirv.sh等各自负责独立的开发流程与发布流程互不干扰。构建本身则由 global.json 锁定的 .NET SDK10.0.103驱动产出位于artifacts目录——发布流程管理的版本号即对应这些构建产物的版本标识。【免费下载链接】sharpemuAn experimental PlayStation 5 emulator for Windows, Linux and macOS.项目地址: https://gitcode.com/GitHub_Trending/sh/sharpemu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考