后端【免费下载链接】prqlPRQL is a modern language for transforming data — a simple, powerful, pipelined SQL replacement项目地址https://gitcode.com/gh_mirrors/pr/prql点击查看免费下载PRQLPipelined Relational Query Language是一个以 Rust 实现的管道化 SQL 替代语言其编译器prqlc与语言书Book、在线 Playground、网站共同维护在同一个仓库中。本文以仓库内 Contributing 指南 为骨架结合 Development 文档、编译器架构说明、语言设计文档 与根目录 Taskfile.yaml 等源码级材料系统讲解如何参与 PRQL 贡献包括贡献方向、开发环境搭建、提交与合并规范、测试金字塔、编译器架构速览、语言设计原则以及发布流程。读完本文你将具备从找到一个 Good First Issue到合入一个带快照测试与变更日志的 PR的完整实战能力。一、为什么贡献 PRQL项目现状与参与入口PRQL 正在从备受关注的新项目演化为被用于日常工作、被集成进各类工具的成熟项目官方明确表示正在积极寻找协作者来引领这一增长。参与社区的第一步不一定是从写代码开始官方在 Contributing 指南 中给出了由浅入深的参与方式为仓库点亮 Star并把 PRQL 推荐给身边值得交流意见的人订阅项目的新版本发布Releases第一时间了解功能迭代关注官方 Twitter 账号、加入官方 Discord 社区在 GitHub 上寻找标记为Good First Issue的 issue 并开始贡献代码加入双周开发者电话会fortnightly Developer Call其日程可以订阅同目录下的 fortnightly-dev-call.ics 日历文件。从仓库结构看本项目是一个典型的 monorepoprqlc/存放 Rust 编译器本体、CLI 与各语言绑定web/存放语言书Book、网站website与 Playgroundgrammars/存放各编辑器的语法高亮定义。这意味着无论你的技术栈是 Rust、前端还是文档写作都能找到适合自己的贡献位置。二、四个主要贡献方向官方将大型贡献划分为四个方向每个方向都有独立的 issue 标签与协作方式。2.1 编译器Compiler任何 Rust 水平都可以上手编译器用 Rust 编写工作量足够大以至于任何 Rust 经验水平都足够开始贡献。项目维护了一批经过筛选、上下文充足的good first issue这些 issue 被刻意设计为有足够背景信息就能动手官方也非常欢迎在上下文缺失时提问。开始前建议阅读两篇材料Development开发环境与工作流总览编译器架构prqlc各编译阶段的划分与数据流。仓库中的实际实现位于 prqlc/prqlc/src其中parser.rs、semantic/、sql/分别对应架构文档中的三大阶段详见第六节。2.2 绑定与集成Bindings integrations让 PRQL 走进既有工具链PRQL 要成功就必须出现在人们已经在用的语言与工具中。官方列出的切入点包括完善现有各语言绑定的功能、文档与打包发布如果你熟悉某个尚未提供绑定的生态的打包方式为它创建新的 PRQL 绑定极具价值如果你日常使用的数据查询工具适合集成 PRQL可以向 PRQL 或该工具提出建议若是开源工具直接构建并分享一个原型。仓库中现存绑定位于 prqlc/bindings包括 .NETC#、Elixir、Java、JavaScriptwasm、PHP、C/Cprqlc-c与 Pythonprqlc-python每个绑定目录都带独立的 README 与测试。相关 issue 统一使用Integrations标签。2.3 语言设计Language design在 GitHub issues 中共同决策新语言特性通常在 GitHub issues 中决策多使用language design标签。即使不写编译器代码你也可以参与发现编译器产生错误结果时提交 bug 报告——可以直接用在线 Playground 复现在 issue 中补充难以用 PRQL 表达的查询示例尤其是比 SQL 更难表达的场景积累足够示例后提出语言变更建议。官方特别强调没有示例支撑的建议很难讨论请务必让建议扎根于具体示例。语言设计背后的方法论详见本文第七节。2.4 文档、网站与推广Marketing改进网站仓库维护着带web标签的网站相关 issue欢迎有一定设计能力的人参与贡献文档小到修正一段令人困惑的表述或一个错别字大到重构整个文档章节都可以向更多人介绍 PRQL找到可能对 PRQL 感兴趣的用户群体帮助他们上手并把他们的需求反馈给项目。三、开发环境搭建从两分钟上手到完整环境Development 文档 将环境搭建分为最小环境与完整环境两级官方明确把搭建过程简单当作项目价值观——如果某个环节不够顺畅可以在 GitHub issue 中反馈维护者会热情协助并用反馈改进脚本与说明。3.1 最小开发环境两分钟起步只需要两个步骤即可拥有足以导航、编辑、测试编译器代码的本地环境安装rustup与cargoRust 官方工具链。建议非必需安装快照测试工具cargo-instacargo install cargo-insta完成克隆后运行prqlccrate 的单元测试即可验证环境cargo test --package prqlc --lib如果想运行测试并自动更新快照cargo insta test --accept --package prqlc --lib这就是开始向编译器提交首个贡献所需的一切。3.2 完整开发环境四种方案对于更高级的开发例如编译 wasm、预览网站官方提供四种方案方案一使用项目的task在 macOS 上验证通过amd64 Linux 应可用其他平台包括 Windows 不可用因为它依赖brew安装 Task。运行setup-dev任务它会执行根目录 Taskfile.yaml 中的命令用cargo、brew、npm、uv安装依赖并建议一些 VS Code 扩展task setup-dev从根目录 Taskfile.yaml 的实现看setup-dev会依次安装cargo_crates变量中列出的工具包括bacon、cbindgen、cargo-audit、cargo-insta、cargo-llvm-cov、cargo-release、cargo-nextest、mdbook系列与wasm-bindgen-cli等、检查/建议 VS Code 扩展rust-analyzer、mitsuhiko.insta、prql-lang.prql-vscode等、检查brew_dependencieshugo、jq、npm、uv、pre-commit、python3、安装maturinPython 绑定构建工具与 npm 全局依赖并执行pre-commit install-hooks与rustup component add llvm-tools-preview。setup-dev还有前置条件要求系统存在clang用于编译测试依赖duckdb-rs缺失时会给出安装提示。方案二逐项安装工具cargo-insta更新快照测试Python多数系统自带可用cargo test是否全量通过来验证若不通过需确保 Python 3.9用于编译prqlc-python涉及网站、Playground、Book 或发布产物的贡献才需要额外工具缺什么时错误信息会足够清晰届时可从根目录 Taskfile.yaml 复制对应的安装命令。方案三使用 Dev Container项目提供devcontainer.json与预构建的开发容器基础镜像。Rust 工具已预装Node.js、Python 等会在构建容器时安装。推荐搭配 GitHub Codespaces 或 VS Code Dev Containers 扩展使用。方案四nix 开发环境核心团队成员在 Linux 上使用目前不支持 Mac根目录 flake.nix 提供 3 个开发环境环境名用途default构建编译器web编译器 网站full编译器 网站 编译器各绑定使用方式# 首次安装 nix 并启用 flakesnix-command flakes 实验特性 nix develop # 默认环境 nix develop .#web # web 环境 nix develop .#full # full 环境可选安装direnvnix-direnv在.envrc中写入use flake .#full进入仓库时自动加载 shell。四、贡献工作流提交、合并与变更日志PRQL 的协作方式与大多数 GitHub 项目一致——开一个 Pull Request 提出建议的改动。4.1 提交规范用户可见的变更必须写变更日志在 CHANGELOG.md 对应小节加一行格式为{message}, (contributor, #X)其中X是 PR 号。由于 PR 号在 PR 打开后才存在该条目通常以同一分支上的后续提交补充若遗漏了欢迎单独提交一个只含变更日志条目的 PR。提交信息遵循 Conventional Commits格式并通过action-semantic-pull-request自动化校验。4.2 合并文化快速合并、测试把关、及时回滚官方明确的合并哲学是任何让 PRQL 变得更好的代码都值得合并PR 不需要完美不需要解决大问题只需方向正确、取得增量进展、对当前状态表述清楚便于他人继续推进但涉及语言的非平凡改动、库的大规模重构等场景需要先达成社区共识有合并权限且对 PR 有信心的人可以直接合并没有权限的作者在提交几个 PR 后通常也会获得权限代码质量主要通过自动化测试来保证PR 几乎总需要带一个测试来证明增量进展如果改动破坏了功能却没有破坏测试说明测试不足如果改动破坏了既有测试例如改了外部 API则提示合并需谨慎并征求他人意见PR 评审用于提供上下文、具体协助与大决策协作。格式/习惯之类的 nits 评审被视为建议而非强制任务欢迎用自动化测试与 lint 把这些建议固化下来合并后仍可继续评审贡献者应把实质性反馈纳入后续 PR若 PR 的实际影响与预期不符、或共识不足应快速回滚——回滚再重做是快速前进的标志同样可接受的方式是注释掉错误的测试或快速修复底层问题。4.3 针对开发者的内环工作流仓库根目录的 CLAUDE.md 也记录了一套开发实践可作为参考开发期间用task prqlc:test约 5 秒的内环测试提交前用task prqlc:pull-request约 30 秒的完整检查仅当改动跨 JS/Python/wasm 绑定时才运行task test-all约 2 分钟。测试偏好使用内联快照insta::assert_snapshot!先用空字符串初始化再以--accept自动填充期望输出。五、测试金字塔PRQL 如何保证改得快且不出错PRQL 采用金字塔式测试策略底层是快速、聚焦的测试提供开发时的低延迟反馈上层是较慢但更广的测试确保项目演进中不漏掉问题。官方明确其方法与 matklad 的《How to Test》理念一致。从金字塔底部到顶部依次为静态检查Static checks通过pre-commit执行定义在.pre-commit-config.yaml保证代码健康与风格一致。本地运行task lint # 或 pre-commit run -a这些检查大多能自动修复发现的问题且大部分也会在 GitHub 上每次提交时运行自动产生的修改会以追加提交的形式加到分支上。此外 GitHub 上还会自动运行 MegaLinter实验性包含更多 linter。单元测试与内联 insta 快照依赖单元测试快速验证代码基本正确大量使用 Insta 快照测试——它把代码生成的值写成快照让编写与修改测试又快又简单。这类测试是最快运行代码的测试设计为开发时每次保存都运行task prqlc:test # 或 cargo insta test --accept --package prqlc --lib从 prqlc/Taskfile.yaml 的实现看prqlc:test实际执行cargo insta test --accept --dnd -p prqlc-parser -p prqlc --test-runnernextestnextest 不支持的 doctest 单独用cargo test --doc跑随后自动执行cargo clippy --fix修复 lint。文档测试Documentation编译网站、README 与 PRQL Book 中的所有示例验证它们产出预期的 SQL防止代码变更引起意外回归。运行方式cargo insta test --accept相关测试位于 web/book/tests/documentation仓库中snapshots/目录下的documentation__book__...系列快照即为这些示例的 SQL 输出。Book 的章节结构可见 web/book/src/SUMMARY.md。数据库集成测试Database integration tests用带真实数据的数据库跑示例查询确保跨方言生成正确的 SQL。测试代码位于 prqlc/prqlc/tests/integration/dbs运行方式task prqlc:test-all # 或 cargo insta test --accept --featuresdefault,test-dbs依据 dbs 目录的 README进程内数据库DuckDB 与 SQLite无需额外配置即可测试外部数据库Postgres、MySQL、SQL ServerClickHouse 运行器存在但暂未启用通过 docker compose 创建全部步骤由task test-rust-external-dbs覆盖。测试数据以 CSV 存储以保证跨数据库可移植性。注意集成测试依赖 DuckDB需要 clang 编译器macOS 用xcode-select --installDebian 系用apt-get install clangWindows 上duckdb-rs不受支持相关测试会被排除。测试查询建议显式使用sort以保证跨数据库的行序一致。GitHub Actions 三层流水线每次提交只跑与 PR 改动相关的测试改文档就构建文档、改绑定就跑该绑定的测试绝大多数测试应在 5 分钟内完成每次合并到 main跑更广的测试涵盖多操作系统、全部语言绑定、测试代码覆盖率与性能基准本地等价命令为task test-all若合并后失败先回滚提交、修复测试再重新合入每夜nightly跑耗时更长、更不易失败或与代码改动无关的测试如安全检查、多 OS 下的绑定测试、昂贵的计时基准。PR 加上pr-nightly标签即可在合并前提前跑这些测试。测试金字塔的目标是让我们能快速改动。如果测试反而拖慢了改动或缺少能增强信心的测试官方欢迎直接提 issue。六、编译器架构速览贡献编译器的必读背景编译器架构文档 描述了prqlc的编译流水线。从源码结构看prqlc/prqlc/src 下的parser.rs、semantic/、sql/与架构文档的各阶段一一对应。整体流程分为三大阶段各子阶段及其 AST 类型如下阶段子阶段使用的 AST 类型parse解析lexer词法字符串 → LRLexer Representationparse解析parser语法LR → PRParser Representationsemantic语义ast_expandPR → PLPipelined Languagesemantic语义resolver解析器PLsemantic语义flatten扁平化PLsemantic语义lowering降级PL → RQRelational Querysqlpreprocess预处理RQsqlpq-compilerRQ → PQPartitioned Querysqlpostprocess后处理PQsqlsql-compilerPQ →sqlparser::astsqlcodegen代码生成sqlparser::ast→ 字符串三个阶段的具体职责词法与语法分析PRQL 源码先由名为 lexer 的 Chumsky 解析器切分为 token 流LR再解析为语法树 ASTPR。语义分析解析标识符、提取声明、确定每个表达式各步骤的表列血统lineage。声明一个RootModule其中持有将可访问名字映射到声明的Module。解析过程包括为每个Expr/Stmt节点分配 ID把函数声明与变量定义提取进相应Module可通过RootModule::module访问在 module 中查找标识符对应的声明替换为在根模块中保证唯一的全限定名某些情况下还会设置Expr::target_id把from/derive/filter等函数调用从FuncCall转换为更便于后续处理的TransformCall推断表达式类型引用表则用表的 lineage 作类型TransformCall则对输入 lineage 应用变换得到结果类型简单表达式则从ExprKind推断。最后通过Lowering把 PL 转为更严格类型化、信息更少但便于翻译到 SQL 或其他后端的 RQ。SQL 后端把 RQ 转为 PQ中间 AST再转为 SQL。每个关系被转换为一条 SQL 查询流水线被分析并在合适位置拆分为可被单个 SELECT 表示的 AtomicPipelines。拆分采用从后向前的方式先建立所有输出列的列表然后反向遍历流水线遇到与已有变换不兼容的变换或遇到无法在当前位置物化的表达式例如 WHERE 子句中的窗口函数时即拆分。这一过程也叫anchoring锚定把列定义锚定到输出查询的特定位置。期间sql::pq::context中的AnchorContext跟踪查询中的表实例防止混淆同一张表的多个实例、列定义计算列或表列引用、列名RQ 定义或生成的。对贡献者而言理解这张表就能快速定位改动落在哪一层改语法看 parser改名字解析与类型看semantic/resolver改 SQL 生成看sql/。七、语言设计用关系思考而不是用 SQL 思考语言设计文档 提出了一个对贡献者至关重要的方法论。PRQL 本质上是一个到 SQL 的转译器这容易让语言设计滑向PRQL 特性如何翻译成 SQL的思维PRQL feature - SQL feature - relational result但这种思考方式是有缺陷的因为它不能很好地建模特性之间的交互SQL 行为有时具有误导性子查询的顺序不会延续到父查询甚至在方言之间有差异如集合运算。正确的思考方式是把 PRQL 特性看作如何影响 PRQL 表达式而多数情况下即如何影响关系PRQL feature - relation | v PRQL feature - relation | v relational resultSQL 只在最后一步——关系关系表达式被翻译为 SQL 表达式时才进入思考。这解释了为什么贡献语言特性时应当以关系变换为论证核心也呼应了语言设计建议必须附带示例的协作规范。八、网站、绑定与发布8.1 网站、Book 与 Playground网站与 Book、Playground 一起发布来源是发布 tag 以及此后任何推送到web分支的提交。web分支指向最新发布 网站专用修复这样 Playground 中的编译器行为与最新发布一致同时允许以比每次发布更短的循环修复文档错误。因此针对 Playground、Book 或网站的修复 PR 应加上pr-backport-web标签bot 会在原分支合并后自动把改动合并回web分支。本地运行三个组件定义于 web/Taskfile.yaml# 运行主网站 task web:run-website # 运行 PRQL 在线书Book task web:run-book # 运行 PRQL Playground task web:run-playground8.2 绑定单仓库 vs 独立仓库各语言绑定有的在本 monorepo 内、有的在独立仓库。官方给出了选择依据的框架因素理由示例是否有人愿意维护独立仓库独立仓库对核心团队维护成本更高tree-sitter-prql维护良好能否独立于编译器变更独立仓库无法与编译器同步变更prql-vscode可以落后于语言演进独立仓库是否更能吸引新贡献者全是 Rust 代码的 monorepo 对其他语言开发者不够友好prql-vscode曾吸引纯 JS 贡献者是否有独立仓库的惯例少数生态要求独立仓库homebrew-prql作为 Homebrew tap 必须独立命名8.3 发布流程当前采用半自动化发布流程核心步骤若版本号需要调整运行cargo release $version --no-publish --no-push --execute --no-verify --no-confirm --no-tag task prqlc:test-all设置版本并提交 PR否则沿用上次发布的补丁号。更新 CHANGELOG.md把## [unreleased]改为新版本号与日期并整理条目。该章节会原样成为发布说明——发布工作流从被 tag 的提交处读取它因此标题必须以## $version开头。若修复了非作者报告的 issue在条目中致谢格式如(pr-author, #5639; reported by issue-reporter)。确认所有目标改动已合入 main 后推送 taggit switch main git pull git tag $version git push origin $versiontag 触发发布工作流把 release 创建为draft内容为 changelog 章节上传prqlc二进制、.deb、.rpm到草稿全部就绪后发布再发布各软件包与网站。发布作业位于release与github-pages环境之后需要在运行页批准待处理的部署。之所以用 tag 而非 release 启动是因为 GitHub 的 immutable-releases 设置拒绝向已发布的 release 上传资产若运行中途失败需先删除残留的未发布草稿再重跑。运行cargo release patch ...把版本提升到下一个开发版本并提交 PR重建下一周期的## [unreleased]章节。版本号同时嵌入prqlc与 Book 的快照中task prqlc:test-all会一并接受。检查是否有需要推进的里程碑。检查 README.md 的Current Status是否反映项目现状。九、核心团队与获取帮助如果在 GitHub 或 Discord 等常规渠道没有得到回应可以联系核心团队Contributing 指南 中列出的成员aljazerzen— Aljaž Mur Erženmax-sixty— Maximilian Rooseitsupi— SHIMA Tatsuyasnth— Tobias Brandt文档同时感谢了此前担任核心团队成员的人Core team Emeritus包括charlie-sandersCharlie Sanders。官方强调 Discord 上有大量乐于助人的开发者编译器相关问题即使上下文缺失也可以放心提问。十、常用命令速查目的命令安装快照测试工具cargo install cargo-insta跑prqlc单元测试cargo test --package prqlc --lib跑测试并接受快照cargo insta test --accept --package prqlc --lib一键搭建完整开发环境task setup-devnix 完整环境nix develop .#full内环测试约 5stask prqlc:test提交前完整检查约 30stask prqlc:pull-request跨绑定全量测试约 2mintask test-all本地 linttask lint/pre-commit run -a数据库集成测试cargo insta test --accept --featuresdefault,test-dbs运行 Book 本地预览task web:run-book运行 Playground 本地预览task web:run-playground编译查询为 SQLcargo run -q -p prqlc -- compile 文件或 stdin无论你想贡献的是编译器核心逻辑、某个语言的绑定、文档与网站还是语言设计本身本文覆盖的路径——从找到 Good First Issue、搭建环境、跑通测试金字塔到按规范提交 PR 并跟进发布——都已在仓库中具备完整的工具链与文档支撑。任何让 PRQL 变得更好的改动无论大小都值得被合并。赞分享后端【免费下载链接】prqlPRQL is a modern language for transforming data — a simple, powerful, pipelined SQL replacement项目地址https://gitcode.com/gh_mirrors/pr/prql点击查看免费下载相关推荐PRQL 贡献者开发指南从两分钟搭建编译环境到测试金字塔与发布工作流PRQL 贡献者开发指南从两分钟搭建编译环境到测试金字塔与发布工作流 PRQLPipelined Relational Query Language是一个后端Cog 贡献者开发指南从环境搭建、测试体系到发布流程的完整实践Cog 贡献者开发指南从环境搭建、测试体系到发布流程的完整实践 本篇指南面向希望为 Cog面向机器学习模型的容器化工具贡献代码的开发者。Cog 使用 GoMLOps容器模型推理服务开发工具Open3D开发者进阶之路源码编译、测试体系与社区贡献完整攻略Open3D开发者进阶之路源码编译、测试体系与社区贡献完整攻略 Open3D 是一款现代 3D 数据处理开源库 提供点云、网格等数据结构与配准、重建、可视化计算机视觉图形学3D渲染科学计算创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
