拓十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

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

HomeBox 贡献指南:从开发环境搭建到发布流程的完整上手实践

HomeBox 贡献指南:从开发环境搭建到发布流程的完整上手实践 后端前端【免费下载链接】homeboxA continuation of HomeBox the inventory and organization system built for the Home User项目地址https://gitcode.com/gh_mirrors/home/homebox点击查看免费下载本文以仓库根目录的 CONTRIBUTING.md 为骨架面向想要为 HomeBox面向家庭用户的库存与组织管理系统贡献代码的开发者系统讲解分支协作规范、开发环境搭建、前后端开发工作流与版本发布流水线。读完本文你将能够独立完成一次从main分支拉取特性分支、编写测试、跑通 lint 与 CI 检查、提交 PR并理解维护者如何通过打标签触发自动化发布的全过程。文中所涉命令、依赖版本与配置均以当前仓库实际内容为准。一、项目概览与协作模型HomeBox 是一个面向家庭用户的库存Inventory与组织Organization管理系统仓库采用Go后端 API Vue 3 / Nuxt前端的经典前后端分离结构后端位于 backend 目录Go 模块声明见 backend/go.mod当前要求 Go 1.26.0使用 ent 作为 ORM、chi 作为 HTTP 路由框架数据层支持 SQLite 与 PostgreSQL前端位于 frontend 目录是基于 Vue 3 与 Nuxt 的应用当前 Nuxt 版本为 4.4.7包管理器为 pnpm见 frontend/package.json使用 Tailwind 与 shadcn-vue 组件体系。在贡献代码之前需要先理解两条最基本的协作约定以 GitHub 作为协作枢纽代码托管、Issue 与功能请求跟踪、Pull Request 接收都围绕 GitHub 展开main分支是唯一开发主线所有 PR 都必须从特性分支合并到main禁止直接在main上开发。从源码结构看CI 流水线.github/workflows/pull-requests.yaml还同时监听main与vnext分支的 PR后者是预留给下一大版本迭代的分支。日常贡献者只需聚焦main。二、分支流程一次标准 PR 的五步走CONTRIBUTING.md 给出了提交 PR 的五个标准步骤逐条结合仓库实际说明如下Fork 仓库并从main创建新分支。在自己的 Fork 中执行git checkout -b feature/my-change main保持特性分支命名语义化如feature/xxx、fix/xxx、docs/xxx便于维护者审阅新增代码必须补测试。后端 Go 测试与前端 TypeScript 测试的组织方式见后文「开发注意事项」仓库中已有大量可参照的测试基座例如后端 backend/internal/core/services/service_entities_test.go、前端 frontend/test/e2e/login.browser.spec.tsAPI 变更必须同步更新文档。HomeBox 的 API 文档由 Swagger 注解自动生成修改后端接口后需要重新生成文档task swag产出的 OpenAPI/Swagger 文档见 docs/public/api/确保测试套件与 linters 全部通过。合并前 CI 会并行跑后端单测、前端测试与 Playwright 端到端测试见 .github/workflows/pull-requests.yaml 中引用的三个 partial workflow本地可用task pr一次性预演全部检查详见第六节发起 Pull Request。PR 目标分支为mainGitHub 会自动挂载 CI 检查状态全部通过后等待维护者 review 与 merge。三、开发环境搭建3.1 前置依赖清单官方推荐优先使用项目自带的devcontainer.devcontainer/目录使用 VSCode 打开仓库时会提示在容器内重新打开容器已预装 Go 1.26 特性并执行task setup见 .devcontainer/devcontainer.json 的features与postCreateCommand开发者无需手工安装任何工具。如果不用 devcontainer则需要在宿主机安装以下工具括号内为当前仓库实际使用的版本依据工具用途版本依据Go后端编译与单元测试backend/go.mod 声明go 1.26.0CI 中actions/setup-go使用 1.26见 .github/workflows/binaries-publish.yamlSwaggoswag从 Go 注解生成 Swagger 文档task setup中执行go install github.com/swaggo/swag/cmd/swaglatestNode.js前端工具链运行时前端包管理器要求 pnpm构建产物为 Nuxt 静态站点pnpm前端依赖安装与脚本执行frontend/package.json 声明packageManager: pnpm10.28.0CI 使用 pnpm 10Taskfile可选但推荐统一封装全部开发命令仓库根目录 Taskfile.ymlversion: 3python3代码生成辅助官方说明大部分系统已预装用于代码生成环节版本提示CONTRIBUTING.md 中写的 Go 1.19 与 Node.js 16 是历史最低要求当前仓库已演进到 Go 1.26 与 pnpm 10 时代请以本仓库实际版本为准。3.2 一键初始化与任务总览安装 Taskfile 后先看一眼全部可用命令task --list-all任务清单来自 Taskfile.yml覆盖依赖安装、代码生成、后端运行、前端开发、测试、CI 模拟与发布预检。随后执行一键初始化task setup该命令实际执行的内容见 Taskfile.yml 的setup任务为go install github.com/swaggo/swag/cmd/swaglatest go install github.com/pressly/goose/v3/cmd/goosev3.8.0 # 数据库迁移工具 cd backend go mod tidy cd frontend pnpm install不习惯 Taskfile 的开发者也可以直接逐条执行上述命令效果等价。四、开发注意事项后端API4.1 启动开发服务器task go:run该任务Taskfile.yml 的go:run的执行细节值得注意前置依赖generate会先跑一遍完整代码生成ent 数据库代码 → Swagger 文档 → TypeScript 类型首次运行耗时较长属正常现象环境变量任务为本地开发预置了HBOX_DEMOtrue与UNSAFE_DISABLE_PASSWORD_PROJECTIONyes_i_am_sure。其中后者是「仅在本地开发服务器上把密码哈希退化为明文」的便利开关Taskfile 顶部注释特别提醒这个变量绝不能全局设置——若作用于go:test/go:coverageGo 测试套件会走明文分支而非 argon2id导致 CI 中的TestTimingEqualizationHashIsValidArgon2测试失败数据库默认使用 SQLiteHBOX_DATABASE_DRIVERsqlite3路径.data/homebox.db带 WAL、busy_timeout 等 pragma无需额外部署数据库即可开发。如需用 PostgreSQL 开发运行task go:run:postgresql该任务会覆盖数据库连接相关环境变量driverpostgres、localhost:5432、用户/密码/库名均为 homebox、禁用 SSL。4.2 两条硬性约定CONTRIBUTING.md 对后端开发明确了两条约定API 服务器不会自动热重载。go run进程在代码修改后不会自动重启每次改动需要手动终止并重新执行task go:run。这与常见的前端 HMR 体验不同请养成「改完重启」的习惯测试语言分工明确单元测试必须用 Go 编写与业务代码同目录、以_test.go结尾端到端/用户故事测试则应使用 TypeScript 编写并复用前端目录下的 client 库。仓库后端已存在大量 Go 测试可作模板例如 backend/internal/data/repo/repo_entities_test.go、backend/app/api/middleware_ratelimit_test.go。运行后端测试与覆盖率task go:test # go test ./...可透传 gotestsum 参数 task go:coverage # -race 竞态检测 覆盖率报告app/internal/pkgs 三个包五、开发注意事项前端5.1 启动前端开发服务器task ui:dev对应命令为pnpm dev --no-forkTaskfile.yml 的ui:dev。前端是 Vue 3 Nuxt 应用使用 Tailwind 与 shadcn-vue 组件体系这一技术栈在 frontend/package.json 的依赖中可得到印证nuxt4.4.7、vue3.5.20、tailwindcss3.4.19、shadcn-nuxt2.2.0。5.2 自动化测试与已知注意点前端测试使用Vitest监听模式运行task ui:watch # pnpm run test:watch相关脚本定义在 frontend/package.jsontest:watch以监听模式运行test:ci以--no-file-parallelism串行方式跑完整套件用于 CI。CONTRIBUTING.md 特别提醒一个实测经验前端测试依赖 API 服务器在运行且某些场景下首次运行会因竞态条件失败——此时不要慌直接重跑一次通常即可通过。这与 Taskfile.yml 中test:ci先编译并后台启动backend/api、sleep 15再跑测试的设计互为印证。前端其他质量门禁task ui:check # pnpm run typecheck —— Nuxt 类型检查 task ui:fix # pnpm run lint:fix —— Prettier ESLint 自动修复六、提交 PR 前的完整自检task prTaskfile 专门封装了「PR 提交前必须全部通过」的任务链Taskfile.yml 的pr任务task pr它依次执行task: generate—— 重新生成 ent 数据库代码、Swagger 文档、TypeScript 类型task: go:all——go mod tidygolangci-lint run ./...lint 规则集见 backend/.golangci.yml启用了 errcheck、staticcheck、revive、gocritic 等 20 个 linter 全量 Go 测试task: ui:check—— 前端类型检查task: ui:fix—— 前端 Prettier/ESLint 修复task: test:ci—— 构建后端、启动服务、串行跑前端 Vitest 套件。本地把task pr完整跑绿基本等同于预演了一遍 .github/workflows/pull-requests.yaml 中 PR CI 的检查内容后端单测、前端测试、Playwright e2e可以大幅减少提交后才发现 CI 失败的返工。七、发布流程打标签即触发全自动流水线CONTRIBUTING.md 明确指出发布机制在 GitHub 上创建一个形如vX.X.X的新标签即可触发一次新的 Release 创建。结合仓库 CI 配置可以还原这条完整流水线文档原文Test - Goreleaser - Publish Release - Trigger Docker Builds - Deploy Docs Fly.io DemoTestPR 合并到main后CI 的测试工作流已完成验证Goreleaser推送v*.*.*标签触发 .github/workflows/binaries-publish.yaml。该流水线先构建前端静态产物随后用 GoReleaser 按amd64、arm64、riscv64三种架构矩阵并行构建 Linux/Windows/Darwin/FreeBSD 平台二进制构建配置见 backend/.goreleaser.yaml 与各架构专属配置Publish Release合并各架构 checksum用gh release upload上传二进制压缩包、checksums.txt与 SBOM并通过 SLSA 生成与校验软件供应链证明见 binaries-publish 中的binary-provenance与verification-with-slsa-verifier两个 jobTrigger Docker Builds标签推送同时触发 Docker 镜像构建与发布.github/workflows/docker-publish.yaml、docker-publish-hardened.yaml、docker-publish-rootless.yaml 三个变体对应仓库根目录的三个 DockerfileDeploy Docs Fly.io Demo文档站点与 Fly.io 演示环境随发布自动部署。八、仓库速查索引贡献规范原文CONTRIBUTING.md开发任务封装依赖安装、代码生成、运行、测试、PR 自检、CI 模拟Taskfile.ymldevcontainer 配置Go 1.26、pnpm、task 自动安装.devcontainer/devcontainer.json后端模块与依赖版本backend/go.mod后端 lint 规则集backend/.golangci.yml前端依赖与脚本Nuxt 4、Vitest、pnpm 10frontend/package.jsonPR CI 工作流.github/workflows/pull-requests.yaml发布二进制流水线.github/workflows/binaries-publish.yaml发布产物文档OpenAPI/Swaggerdocs/public/api/后端 Go 测试示例backend/internal/data/repo/repo_entities_test.go前端 e2e 测试示例frontend/test/e2e/login.browser.spec.ts结语从main分支出特性分支、补测试、同步文档、跑通task pr、提交 PR到维护者打vX.X.X标签触发 Goreleaser/Docker/文档全自动发布HomeBox 的贡献链路完整且自动化程度高。对贡献者而言最省力的路径是优先使用 devcontainer Taskfile开发阶段记住「后端改完要手动重启」提交前跑一遍task pr。掌握这套工作流后你便可以顺畅地参与这个家庭库存管理系统的迭代。赞分享后端前端【免费下载链接】homeboxA continuation of HomeBox the inventory and organization system built for the Home User项目地址https://gitcode.com/gh_mirrors/home/homebox点击查看免费下载相关推荐urql 贡献指南从环境搭建到 changeset 发布流程的完整开发实践urql 贡献指南从环境搭建到 changeset 发布流程的完整开发实践 urql 是一个高度可定制、灵活的 GraphQL 客户端它的可扩展性不仅体现在前端Arkime 贡献指南从开发环境搭建、测试规范到发布流程的完整实践Arkime 贡献指南从开发环境搭建、测试规范到发布流程的完整实践 Arkime原 Moloch是一个开源的大规模全包捕获full packet cap网络安全网络后端数据可视化book-to-skill 贡献指南从开发环境搭建到 git-cliff 发布流程的完整实践book to skill 贡献指南从开发环境搭建到 git cliff 发布流程的完整实践 导读 本文围绕开源项目 book to skill 的贡献规范AI 技能上一篇【亲测免费】 探秘SQL Exporter多数据库监控新选择下一篇mPDF深度解析现代PHP PDF生成架构演进与实战指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表