ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

mas 项目贡献指南:Trunk-Based 开发流程、代码质量门禁与发布规范

mas 项目贡献指南:Trunk-Based 开发流程、代码质量门禁与发布规范 CLI开发工具【免费下载链接】mas:package: Mac App Store command-line interface项目地址https://gitcode.com/gh_mirrors/ma/mas点击查看免费下载mas 是一个面向 Mac App Store 的命令行工具macOS 13Swift 6.3/SwiftPM 实现。仓库根目录的 CONTRIBUTING.md 定义了从提出 Issue、Fork 分支、提交前质量门禁Scripts/format与Scripts/lint、测试要求到版本发布与贡献者晋升的完整协作规范。读完本文你将掌握一条可落地的贡献路径如何以main为干线创建 topic 分支、如何通过自动化格式化与静态分析检查、如何编写 Swift Testing 测试以及v1.2.3版本标签与维护者交接机制背后的实现细节。参与之前检索与登记 IssueCONTRIBUTING.md 要求所有贡献者先完成三个准备步骤确保拥有 GitHub 账号用于提交 PRPull Request先检索是否已有相似 Issue避免重复报告若不存在相似 Issue再新建 Issue并选择合适的 Issue 模板、遵循模板内给出的指引填写。同时参与本项目意味着同意遵守 CODE_OF_CONDUCT.md 中的行为准则。这一先检索、后登记、按模板提交的流程是 mas 社区保持 Issue 信息可检索、可追溯的基础。主干开发Trunk-Based Development工作流mas 采用trunk-based developmentmain是唯一的干线trunk。对应的协作约定如下Fork 仓库在 GitHub 上 Fork 本仓库得到你自己的副本克隆 forkgit clone你的 fork将用户名替换为你自己的 GitHub 用户名例如git clone gitgithub.com:your-username/mas.git创建 topic 分支不要直接在main上提交而是从main切出短生命周期分支。例如git checkout -b feature main按逻辑单元提交每次提交应是一个独立的逻辑单元logical unit而不是把互不相关的改动混在一起遵守项目规范遵循 AGENTS.md 中定义的项目约定下文详述提交前执行质量门禁先运行Scripts/format再运行Scripts/lint并修复全部违规详见下一节编写测试为你的改动补充测试如果测试编写遇到困难可以直接先提交 PR 并在 PR 中求助推送并提交 PR将 topic 分支推送到 fork然后提交 PR如果 PR 尚未准备好合并请创建Draft PR表明不可合并状态。AGENTS.md 与 CONTRIBUTING.md 互相印证了这套约定AGENTS.md 明确写出 mainis the trunkBranch topics frommain并将添加或编辑测试反复运行Scripts/format直至无改动反复运行Scripts/lint并修复全部违规列为提交前的固定步骤其中第 2、3 步主要是为人类贡献者准备的Agent 出于节约 token 的考虑可以跳过。开发工具链Scripts/bootstrap 与开发脚本mas 仓库把构建、测试、打包等操作统一封装为Scripts/目录下的 zsh 脚本所有脚本都遵循同一套规范见 AGENTS.md 的 Scripting 小节使用#!/bin/zsh -Ndefgku作为 shebang开头执行. ${0:A:h}/_setup_script加载 Scripts/_setup_script 提供的公共初始化逻辑设置 zsh 选项、环境变量并提供print_notice与ensure_command_available两个辅助函数优先使用 zsh 展开、glob、内置命令而非外部命令。常用入口脚本如下脚本用途Scripts/bootstrap安装Scripts/format与Scripts/lint所需依赖未安装 Homebrew 时会先安装然后brew bundle upgradeScripts/build构建 Swift 包swift build调试构建直接运行Release 构建用Scripts/build -c releaseScripts/setup_libexec把构建产物复制到libexec/bin/mas供 zsh 包装脚本调用Scripts/maszsh 包装脚本调用真实二进制并用jq把 JSON 输出重新排版为表格等易读形式Scripts/test运行测试swift test --disable-xctest -qScripts/package生成手册页并构建.pkg安装包Scripts/version输出当前版本号基于git describe --tags并附加分支名与工作区脏标记其中 Scripts/test 使用--disable-xctest参数印证了项目采用Swift Testing框架而非 XCTest编写测试这一点与 AGENTS.md 的 Testing Requirements 一致。提交前的质量门禁Scripts/format 与 Scripts/lintCONTRIBUTING.md 把运行Scripts/format和运行Scripts/lint并修复全部违规列为提交前的强制步骤。这两套门禁覆盖 Swift、Markdown、YAML、Shell、Git 状态等多个维度。Scripts/format自动格式化Scripts/format 会直接修改代码来修正风格问题依次执行SwiftFormatswiftformat --strict --markdown-files format-strict .对 Swift 源文件及文档中的 Swift 代码块做严格格式化SwiftLint 自动修复swiftlint --fix自动修复可安全处理的 lint 违规Markdown 修复markdownlint-cli2 --fix修正 Markdown 文档格式可执行权限检查扫描Scripts/下非可执行的脚本文件若有则自动补上ax权限并退出提示开发者修正。脚本开头通过ensure_command_available检查markdownlint-cli2、swiftformat、swiftlint是否已安装缺失时会提示运行Scripts/bootstrap或brew install tool安装。AGENTS.md 进一步要求反复运行Scripts/format直到不再产生任何改动。Scripts/lint静态检查不修改代码Scripts/lint只报告、不修改检查链比 format 更完整。它支持两个快捷参数-A跳过 SwiftLint Analyze 环节、-P跳过 Periphery 环节二者可组合为快速检查Scripts/lint -APAGENTS.md 中标注为 quick。完整的 lint 检查清单对应 Scripts/lint 源码包括检查项工具/命令说明Swift 格式swiftformat --lint格式违规会直接判失败Swift 静态分析swiftlint --strictswiftlint analyze结合xcodebuild编译器日志做深度分析可用-A跳过未使用代码periphery scan仅当 macOS ≥ 15 且为 arm64 架构时启用可用-P跳过Markdownmarkdownlint-cli2检查所有*.mdYAMLyamllint -s检查工作流等 YAML 文件Git 状态git diff --check检查空白错误Zsh 语法/bin/zsh -n对Scripts/下每个脚本做语法校验GitHub Actionsactionlint检查 workflow 语法Shellshellcheck -s bash检查Scripts/下脚本编辑器规范editorconfig-checker校验与.editorconfig的一致性可执行权限扫描非可执行脚本与 format 中的检查对应lint 脚本要求actionlint、editorconfig-checker、git、markdownlint-cli2、shellcheck、swiftformat、swiftlint、yamllint全部可用缺失时直接退出并给出安装提示。项目约定与编码规范AGENTS.mdCONTRIBUTING.md 要求贡献者遵循项目指南——这份指南就是 AGENTS.md它是人类与 Agent 共同的规范权威核心内容包括最低版本要求与 Package.swift 中platforms: [.macOS(.v13)]、swift-tools-version:6.3一致Swift 6.3Xcode 26.4macOS 13。源码目录层次Swift 源码按Sources/mas下的三个子目录组织——CommandsCLI 实现、Models数据类型与供应商、Utilities工具函数参见 Sources/mas/Commands、Sources/mas/Models、Sources/mas/Utilities。命令实现模式从 MAS.swift 可以看到mas 的所有子命令都是嵌套在MAS主命令AsyncParsableCommand中的 struct通过 Swift Argument Parser 注册参数组用OptionGroup组合可复用的ParsableArguments类型例如OutdatedAppsOptionGroup命令入口统一实现func run() async所有输出统一走静态的MAS.printer业务逻辑通过AppStoreAction枚举调用如await AppStore.install.apps(...)。项目还通过 PrivateFrameworks 目标以 Objective-C 头文件形式暴露 Apple 私有框架 CommerceKit控制器与 StoreFoundation模型用于向 App Store 部署应用。内容格式要求UNIX 换行、Tab 缩进宽度按 2 计、单行最长 120 字符、删除多余行尾空白、文件以单个换行符结尾。重构守则除非是功能修复或发现规范违规不得随意重排、重命名、重排序、删注释或重写既有代码工具函数仅在单处使用时内联替换工具函数时以更正确、更高效、更简洁的优先级进行。Swift 风格优先级从命名、类型推断、可选值处理??→ 三元 →Optional.map→guard→switch→ … → 强制解包 →fatalError、typed throws、到内存安全严格模式下优先unsafe之外的方案都给出了明确的偏好排序贡献者在提交代码前应自查是否符合这些层次。测试要求Swift Testing 与测试文件命名CONTRIBUTING.md 明确要求编写测试并允许贡献者在测试遇到困难时直接开 PR 求助。仓库的测试基建印证了这一点Package.swift 定义了独立的MASTests测试目标含Resources资源Scripts/test 用swift test --disable-xctest -q运行测试确认测试框架为Swift TestingAGENTS.md 给出了测试文件命名的确定性规则把源文件路径前缀Sources/mas替换为Tests/MASTests并在文件名前加MASTests。例如Sources/mas/Commands/MAS.Version.swift对应Tests/MASTests/Commands/MASTestsMAS.Version.swift。以 MASTestsMAS.Version.swift 为例测试写法是标准的 Swift Testing 风格Test func outputs version() async throws { let actual try await consequencesOf(try MAS.main(try MAS.Version.parse(.init()))) let expected Consequences(nil, \(MAS.version)\n) #expect(actual expected) }这里的consequencesOf来自 Tests/MASTests/Testing/Consequences.swift捕获命令执行后的标准输出与错误与预期结果逐字节比对。测试目录覆盖了Commands下的 Home、List、Lookup、Search、Seller、Version 等命令以及Models下的 CatalogApp、CatalogAppResults 等类型新的功能改动应遵循同样的命名与组织方式补充测试。提交信息与版本发布CONTRIBUTING.md 要求编写好的提交信息good commit messages即主题行简洁、正文说明动机与影响并规定发布提交以v1.2.3格式打标签Release含发布说明发布在 Releases 页面。标签与发布机制在脚本中有具体实现Scripts/version 通过git describe --tags得到最近标签并去掉前导v再附加当前分支名非 main 时与工作区脏标记例如1.2.3-featureScripts/package 用该版本号构建安装包先Scripts/build -c release产出 release 二进制再用swift package generate-manual生成mas.1手册页随后用pkgbuild/productbuild打包出mas-version-archs.pkg并在安装器脚本中声明最低系统版本 macOS 13。因此提交信息规范 vX.Y.Z标签 自动化打包共同构成了 mas 的可追溯发布流水线版本号、标签与安装包三者一一对应。成为贡献者Becoming a ContributorCONTRIBUTING.md 提供了明确的晋升通道当你的若干 PR 被合并后可以通过新建一个标题为Add Contributor: YourGitHubUsername的 Issue 申请加入 contributor 团队。该流程背后是一套约束性的约定不得声称自己是原作者许可证LICENSE中必须保留创始人 argon 的名字其他人的名字可在做出实质性贡献后被追加README.md 中必须保留 argon 的名字Andrew Naylor、GitHub 账号与 X 账号可以按需调整位置。维护者的职责与项目交接CONTRIBUTING.md 同时约束了项目维护者project lead的义务创始人地位不可剥夺argon 必须始终是组织organization的 owner 之一方向自主权除上述约束外维护者对未来项目方向拥有完全控制权交接机制若你是唯一的维护者但无法继续领导项目则必须执行以下任一路径找到愿意遵守并延续既有条款的新维护者接任若找不到则需在 README.md 中添加 unmaintained不再维护徽标通过 X 或邮件联系 argon并把项目所有权交还给 argon。这一条款体现了 mas 社区对作者署名权保留 项目可持续性的双重承诺是仓库治理结构的一部分任何 PR 都不会绕过该结构。小结一条完整的贡献路径综合 CONTRIBUTING.md 与其配套的 AGENTS.md、Scripts/ 工具链一次合格的贡献可以概括为五步先检索并登记 Issue → Fork 并基于 main 创建 topic 分支 → 用Scripts/format格式化、用Scripts/lint清零全部违规 → 按 Swift Testing 规范补充测试Scripts/test 验证→ 按逻辑单元提交并推送 PR未就绪则用 Draft PR。合并后代码遵循 AGENTS.md 的目录与风格约定发布时以v1.2.3标签配合 Scripts/package 产出安装包——这套从代码到发布的全链路规范正是 mas 作为长期维护的开源 CLI 项目得以持续演进的基础。赞分享CLI开发工具【免费下载链接】mas:package: Mac App Store command-line interface项目地址https://gitcode.com/gh_mirrors/ma/mas点击查看免费下载相关推荐Rayhunter 贡献指南从 Issue 规范到 PR 质量门禁与版本发布全流程Rayhunter 贡献指南从 Issue 规范到 PR 质量门禁与版本发布全流程 Rayhunter 是一个基于 Rust 的蜂窝基站模拟器IMSI Ca网络安全通信Elsa Workflows 贡献指南Trunk Based 开发流程、PR 规范与 ADR 记录实践Elsa Workflows 贡献指南Trunk Based 开发流程、PR 规范与 ADR 记录实践 本文以 Elsa Workflows 官方贡献规范后端工作流自动化流程编排低代码RustFS 贡献指南开发环境搭建、代码质量门禁与 Pull Request 提交规范RustFS 贡献指南开发环境搭建、代码质量门禁与 Pull Request 提交规范 RustFS 是一个开源、兼容 S3 的高性能对象存储系统其代码库横后端对象存储分布式存储创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表