Wekan 开发者文档指南基于 Meteor 的开源看板开发环境、构建管线与贡献流程【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan本文以仓库内 docs/DeveloperDocs/Developer-Documentation.md 为主体骨架并结合仓库源码package.json、.meteor/、client/features/、models/、tests/等进行补充印证。Wekan本仓库package.json标注版本 v11.72.0是一个基于 Meteor 全栈 JavaScript 平台构建的开源看板应用。本文面向想要从使用者转变为贡献者的开发者完整梳理 Wekan 的代码风格约定、开发环境搭建、meteor开发循环、代码检索方法、Pull Request 提交流程、构建管线JADE Stylus Blaze mutation 模式以及国际化与 Trello 导入等关键主题。读完本文你将掌握在本地搭建 Wekan 开发环境、定位代码、提交合格 Pull Request 的完整闭环。一、代码风格指南以 Meteor Style Guide 为准Wekan 的代码风格遵循官方 Meteor style guideJavaScript 部分。文档明确要求在做出任何有意义的贡献之前请先阅读 Meteor 风格指南。这意味着变量命名、函数组织、文件结构尽量与 Meteor 社区约定保持一致遵循 Meteor 的模块化与导入import/export体系而非全局变量堆叠模板、方法、发布publication的职责划分遵循 Meteor 惯例。仓库中实际的风格约束还有一层隐性规定开发者文档特别强调不要使用 Prettier、ESLint 等代码格式化工具来自动重排代码参见该文档中 Do not use code formatters like Prettier and ESLint 一节。这一点与大多数现代前端项目相反——Wekan 希望贡献者保持手写代码的自然格式同时尽量与既有文件风格一致。后续Travis CI 与 ESLint一节还会说明 lint 的边界lint 仅用于捕获未定义变量等硬错误而不是统一格式化。二、Wekan 如何工作开发者的背景阅读清单开发者文档整理了一批关于 Wekan 如何工作以及如何开发 Wekan的故事性材料用于帮助新贡献者建立心智模型。虽然这些链接指向外部讨论但我们可以从仓库中印证它们对应的真实实现主题包括主题仓库中的对应实现Login code登录代码config/accounts.js 配置 AccountsTemplatesserver/authentication.js 提供Authentication访问权限检查对象server/header-login.js、server/lastActiveOnLogin.js 处理登录后的副作用实时看板更新realtime board updatesMeteor 的发布/订阅体系见 server/publications/boards.js、server/publications/cards.js配合 models/boards.js、models/cards.js 的集合定义Mobile Web 界面client/ 下的响应式 Blaze 模板与 public/ 中的 Web App Manifest、PWA 资源public/site.webmanifest.default、public/pwa-service-worker.js如何添加 RTL 支持imports/i18n/ 国际化体系与 docs/Features/Editor/RTL 相关文档如何添加依赖dependency见下文添加依赖小节与.meteor/packages、package.json直接相关阅读建议浏览这些主题时配合仓库中的 docs/DeveloperDocs/Directory-Structure.md目录结构详解与 docs/DeveloperDocs/Debugging.md调试指南一起阅读能更快建立功能 → 文件 → 集合 → 模板的映射关系。三、构建代码与提交 Pull Requestmeteor开发循环开发者文档对开发循环给出了关键说明当你启动meteor命令时它会监视 wekan 目录及其子目录中文件的变化一旦检测到代码变更就自动开始重建 bundle并在重建完成后自动刷新浏览器。这正是 Meteor 的核心开发体验。仓库中的.meteor/release文件记录当前使用的 Meteor 版本为METEOR3.5.2.meteor/packages则列出了全部 Meteor 包详见下文。此外文档还提示关注 Meteor 更新日志中提到的hot reload热重载新特性它可以让刷新更快——这也体现在 .meteor/versions 中的hot-code-push1.0.5上Meteor 经典的 HCP 机制以及现代 Meteor 的 HMRHot Module Replacement。开发者文档引用了 docs/Features/Editor/Emoji.md 的 How you could add another plugin 一节作为构建代码并提交 Pull Request的完整范例——该文档以 Markdown 编辑器添加新插件为例展示了从需求、实现到集成的一整套流程是贡献者上手的最佳样例。四、开发环境与编辑器VSCode / VSCodium开发者文档推荐使用VSCodium去除了微软跟踪代码的 VSCode 发行版并建议安装以下插件Prettier用于右键格式化 JavaScript 代码注意这与不要使用格式化工具的约定并不矛盾——Prettier 插件是供开发者按需手动格式化本地代码的而不是 CI 里强制执行的步骤其他可选插件Meteor、Jade、Stylus、Dockerfile 等语言支持插件。仓库根目录存在 .vscode/VSCode 设置与 .editorconfig跨编辑器统一编码风格说明项目同时为多种编辑器提供了基础约定。五、快速定位代码find.sh脚本这是 Wekan 贡献者最常使用的工具之一。仓库根目录的 find.sh 是一个 Bash 脚本作用是在所有子目录中查找文本同时忽略所有临时/生成目录node_modules已安装的 Node 模块.buildWekan 的发布 bundle由源码合并而成不要编辑会被删除重建.meteor具体为.meteor/local等运行时目录与.gitgit 历史。脚本签名是./find.sh text-to-find查找结果用less分页显示。文档给出的示例是cd wekan ./find.sh js-search运行后会看到.jade模板文件搜索输入框所在的模板、.js文件搜索逻辑实现以及.styl文件CSS 样式。从源码结构看脚本使用find . -type f配合多条-not -path排除规则并用grep -I跳过二进制文件。实操提示由于脚本最终通过less分页交互式终端中可用/继续搜索、q退出。这套流程非常适合回答某个功能如卡片搜索、卡片归档的代码在哪里这类问题。六、开始开发Getting Started环境与两种方式6.1 官方开发环境说明开发者文档说明Wekan 的开发主要在 Ubuntu 20.10 64bit 上进行但在任何 Debian、Ubuntu、WSL Ubuntu 20.04 上均可构建Mac 与 Windows 也有可行路径Windows 上可通过choco install -y meteor安装 Meteor然后根据提示执行meteor add ...或meteor npm install --save ...。新贡献者的入门建议浏览旧 [pull requests] 了解项目历史与代码演进阅读 Wekan 源码可使用 gitk 等 git 历史查看 GUI阅读 Meteor 官方文档 记录的 Meteor 版本METEOR3.5.2为准**其他版本信息见 Dockerfile当前基于debian:trixie构建。6.2 方式一Docker 从源码构建文档推荐的最新方式克隆 wekan/wekan 仓库更新docker-compose.yml文件中的ROOT_URL等环境变量详见仓库根目录 docker-compose.yml 中注释安装 Docker从源码构建并启动docker compose up -d --build6.3 方式二Docker 开发环境非最新方式文档还提及 wekan-dev 这个用于 Wekan 开发的 Docker 环境方案。此外docs/DeveloperDocs/Build-from-source.md 提供了从源码构建的完整分步说明docs/DeveloperDocs/Build-and-Create-Pull-Request.md 则专门讲解构建 提交 PR的组合流程两者都是本节的重要补充。6.4 仓库构建配置速览Meteor 包清单.meteor/packages 明确列出依赖构建系统ecmascript、standard-minifier-js、rspack1.3.0、modern-browsers、模板blaze3.0.2、集合aldeed:collection2、aldeed:schema-index、reywood:publish-composite、mongo、账号体系accounts-password、accounts-2fa、accounts-express以及wekan-ldap、wekan-accounts-cas、wekan-accounts-saml、wekan-accounts-sandstorm、wekan-oidc等自维护包、路由ostrio:flow-router-extra、UIostrio:i18n、wekan-markdown、wekan-fullcalendar、wekan-fontawesome与测试meteortesting:mochanpm 依赖package.json 声明了meteor.mainModule为client/main.jsserver/main.js测试模块为client/lib/tests/index.jsserver/lib/tests/index.js并包含 S3/Azure/Google Cloud 存储适配、office-open-xml-viewer、exceljs 等大量运行时依赖客户端入口client/imports.js 按固定顺序导入 i18n、共享模型、运行时服务、config、client lib、Blaze helpers 与全部client/features/*特性模块——这是理解页面加载了什么的权威清单。七、Pull Request 工作流提交前必读开发者文档对提交 PR 给出了明确规则依赖安装如果包在 Meteor 生态atmospherejs.com可用用meteor add packagename如果在 npm 可用用meteor npm install packagename。以这种方式添加即可无需在构建脚本中 clone 仓库。翻译唯一入口提交 PR 时只对英文翻译文件 imports/i18n/data/en.i18n.json 做增改。其他语言的翻译由 Transifex 平台完成仓库内 .tx 目录即 Transifex 配置文件。修复已有 PR如果你要修复某个已存在的 PR 的问题以评论comment形式添加你的修复不要新开 PR。新功能如果没有已存在的 PR才为它新建 PR。清理调试代码删除所有console.log语句。仓库源码也印证了这一约定——例如 client/features/cards.js 中console.log的数量为 0。移除不需要的提交PR 中多余/错误的提交应被清理文档给出了 rebase 清理提交的方法。八、CI 与 lintTravis 的现状与本地自查开发者文档专门提醒了一个现状注意Travis 目前是坏的总是显示诸如变量未定义或未使用之类的警告和错误所以只要你的代码能跑就忽略 Travis。这一条对新手非常重要——不要把 Travis 的红叉当作自己代码有问题的必然证据。同时贡献者仍应在本地做 lint 自查安装 ESLintnpm install eslint运行npm run lint尝试自动修复eslint --fix filename.js。仓库根目录的 .eslintrc.json 就是 ESLint 配置文件可供本地 lint 使用。文档还提到截至 2018-05-05 可能已失效jsbeautifer 网站可作为备选其设置要点是Indent with 2 spaces两个空格缩进与 JSLint-happy 风格。九、选择要解决的问题Choosing issues to work on开发者文档对选题给出了非常务实的建议自由选题你可以在任意 issue 上工作主动声明在 issue 上留言说明正在处理它并持续给出进展更新一次只做一个一次专注一个 issue做完再做下一个维护个人贡献清单把贡献记录在个人网站上形成可展示的履历记录实现耗时记录每个功能部件的实现时间据此估算类似功能的工作量并事后复盘改进估算方法雇主看重有可验证记录的开发者关于设置项位置通常功能需求已经定义得足够清晰把新的 Settings 选项放在你认为最符合逻辑的位置即可。此外文档强调对评论你代码的人保持友善并吸收那些最有意义的建议。十、构建管线Build PipelineJADE Stylus Blaze mutation 模式这是理解 Wekan 技术栈最关键的一节也是与传统 Meteor 应用差异最大之处10.1 模板JADE 而非 HTML模板使用 JADE 编写而不是纯 HTML仓库 client/components/ 下共 129 个.jade文件重要规则来自 docs/DeveloperDocs/Directory-Structure.md.jade文件放在磁盘上并不会被自动加载每个模板都必须由 client/features/*.js 按名称导入组件.js若被其他组件 import也必须 import 它自己的.jade。测试 tests/templateRegistration.test.cjs 专门校验每个client/components下的.jade都被导入、每个template都解析到已导入的模板——这正是历史上headerBarControls.jade因未被导入而在 All Boards 页面渲染时报 No such template 的教训。10.2 样式Stylus 预编译器CSS 使用 Stylus 预编译器编写.styl源文件最终编译为 CSSfind.sh搜索样式时找的正是.styl文件。10.3 模板体系BlazeLayoutMeteor 模板以BlazeLayout模板方式创建通过 config/router.js 中的 FlowRouter仓库实际使用ostrio:flow-router-extra见 .meteor/packages进行客户端路由账号相关 UI 使用 AccountsTemplates配置在 config/accounts.js。10.4 数据写权限mutations 取代 allow/deny这是 Wekan 架构上最有辨识度的设计项目中定义的大量collections不使用 allow/deny 范式而是使用mutations来定义允许进行哪些操作。从源码结构看这一模式在 models/ 目录中体现得最为彻底每个模型文件如 models/boards.js、models/cards.js、models/lists.js、models/checklists.js不仅定义集合与 SimpleSchema 校验还承载 helpers、mutations、methods、hooks 与引导代码服务端另以 JSON REST API 形式提供接口见 server/apiMiddleware.js 与 openapi/ 下的 API 描述。mutation 模式把允许什么操作显式编码在模型层替代了分散的 allow/deny 规则。10.5 进一步学习路径文档建议查看 Wiki 中的 feature summaries仍在完善中否则就翻阅 git 历史看旧功能是怎么构建的并特别推荐了 Start and Due date开始与截止日期功能的 PR 作为范例。对应地当前仓库中 models/cards.js 的日期字段、client/components/cards/cardDate.jade 与cardDate.js正是该功能的现成实现可以直接研读。十一、国际化Translations新功能必须支持 i18n开发者文档明确要求如果添加新功能请同时支持内置的国际化internationalization能力。具体机制在仓库中非常清晰imports/i18n/ 目录存放 i18n 基础设施index.js、languages.js、moment.js、tap.js、loadHelpers.js等imports/i18n/data/ 下每个受支持语言对应一个*.i18n.json文件当前仓库共 246 个语言文件如en.i18n.json、zh_CN.i18n.json等PR 只改英文源文件en.i18n.json其他语言在 Transifex 平台协作翻译仓库 releases/translations/ 下有拉取 Transifex 翻译并逐 key 合并绝不覆盖人工翻译的工具脚本。因此贡献新功能时的国际化落地路径是在 imports/i18n/data/en.i18n.json 中添加英文 key 与默认文案然后在代码中通过 i18n 辅助函数引用该 key。十二、从 Trello 导入Export From TrelloWekan 支持从 Trello 导入现有看板。仓库中的对应实现包括models/import.js实现importBoard()方法models/trelloCreator.jsTrello 导入的板/列表/卡片重建逻辑models/wekanCreator.jsWekan 自身格式的导入客户端导入界面模板client/components/import/import.jade配套 trelloMembersMapper.js 与 wekanMembersMapper.js 完成成员映射测试侧tests/durableTrelloImport.test.cjs 覆盖 Trello 导入的持久性。十三、目录结构速查与进一步阅读开发者文档将目录结构详述单独成篇docs/DeveloperDocs/Directory-Structure.md。其中一张总表把整个仓库 20 个目录一网打尽最值得记住的几点目录内容关键约束client/浏览器端运行的 Blaze 组件、样式、客户端库.jade必须被 client/features 导入server/仅服务端startup、publications、methods、REST 路由、lib/客户端不可见models/集合、schema、helpers、mutations前后端共享绝不能 importserver/会破坏客户端构建服务端逻辑放在Meteor.isServer或server/lib/imports/i18n、响应式缓存、共享 SimpleSchema、startup非模型非组件的共享代码packages/自维护的 Meteor 包CAS、LDAP、OIDC、Sandstorm、lockout、markdown—config/路由FlowRouter与账号配置—migrations/数据库迁移每个迁移一个文件启动时按序执行schema 非向后兼容变更时必须写迁移tests/*.test.cjs由tests/run-node-suites.cjs运行 Playwright e2e许多测试直接读源码来钉住行为补充两个易混淆点同样来自 Directory-Structure.md.build/是发布 bundlemeteor build .build --directory的产物而_build/是 rspack 的编译输出——任何 Meteor 编译dev 运行、测试、发布构建都会写它是交接产物而非残留_build/已被 gitignore但绝不能加入.meteorignore否则会直接破坏构建。十四、交流渠道与后续学习开发者文档最后指向了 Wekan 社区聊天渠道并提示在开始任何重要贡献前阅读 Meteor 风格指南。结合本仓库推荐的完整学习路径是通读本文涉及的 Developer-Documentation.md精读 Directory-Structure.md 建立全局认知按 Build-from-source.md 与 Build-and-Create-Pull-Request.md 实操本地构建用./find.sh从一个小功能如卡片搜索、自定义字段切入源码用 Debugging.md 中的方法排障遵循本文的 PR 工作流提交贡献。十五、开发与贡献核心要点速查表事项结论代码风格遵循 Meteor Style Guide不要用 Prettier/ESLint 强行格式化Meteor 版本METEOR3.5.2见 .meteor/release本地构建meteor命令启动开发循环改动自动重建并刷新浏览器Docker 方式docker compose up -d --build找代码./find.sh keyword忽略 node_modules/.build/.meteor/.git翻译PR 只改 imports/i18n/data/en.i18n.jsonlintnpm run lint、eslint --fixTravis 状态视为仅供参考提交 PR修旧 PR 用评论、新功能开新 PR、删除所有console.log模板/样式JADE Stylus BlazeLayout.jade必须显式导入数据写权限使用 models 层的 mutation 模式而非 allow/deny以上内容均以当前仓库实际文件为准可作为新贡献者快速上手的第一份地图。【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Wekan 开发者文档指南：基于 Meteor 的开源看板开发环境、构建管线与贡献流程
Wekan 开发者文档指南基于 Meteor 的开源看板开发环境、构建管线与贡献流程【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan本文以仓库内 docs/DeveloperDocs/Developer-Documentation.md 为主体骨架并结合仓库源码package.json、.meteor/、client/features/、models/、tests/等进行补充印证。Wekan本仓库package.json标注版本 v11.72.0是一个基于 Meteor 全栈 JavaScript 平台构建的开源看板应用。本文面向想要从使用者转变为贡献者的开发者完整梳理 Wekan 的代码风格约定、开发环境搭建、meteor开发循环、代码检索方法、Pull Request 提交流程、构建管线JADE Stylus Blaze mutation 模式以及国际化与 Trello 导入等关键主题。读完本文你将掌握在本地搭建 Wekan 开发环境、定位代码、提交合格 Pull Request 的完整闭环。一、代码风格指南以 Meteor Style Guide 为准Wekan 的代码风格遵循官方 Meteor style guideJavaScript 部分。文档明确要求在做出任何有意义的贡献之前请先阅读 Meteor 风格指南。这意味着变量命名、函数组织、文件结构尽量与 Meteor 社区约定保持一致遵循 Meteor 的模块化与导入import/export体系而非全局变量堆叠模板、方法、发布publication的职责划分遵循 Meteor 惯例。仓库中实际的风格约束还有一层隐性规定开发者文档特别强调不要使用 Prettier、ESLint 等代码格式化工具来自动重排代码参见该文档中 Do not use code formatters like Prettier and ESLint 一节。这一点与大多数现代前端项目相反——Wekan 希望贡献者保持手写代码的自然格式同时尽量与既有文件风格一致。后续Travis CI 与 ESLint一节还会说明 lint 的边界lint 仅用于捕获未定义变量等硬错误而不是统一格式化。二、Wekan 如何工作开发者的背景阅读清单开发者文档整理了一批关于 Wekan 如何工作以及如何开发 Wekan的故事性材料用于帮助新贡献者建立心智模型。虽然这些链接指向外部讨论但我们可以从仓库中印证它们对应的真实实现主题包括主题仓库中的对应实现Login code登录代码config/accounts.js 配置 AccountsTemplatesserver/authentication.js 提供Authentication访问权限检查对象server/header-login.js、server/lastActiveOnLogin.js 处理登录后的副作用实时看板更新realtime board updatesMeteor 的发布/订阅体系见 server/publications/boards.js、server/publications/cards.js配合 models/boards.js、models/cards.js 的集合定义Mobile Web 界面client/ 下的响应式 Blaze 模板与 public/ 中的 Web App Manifest、PWA 资源public/site.webmanifest.default、public/pwa-service-worker.js如何添加 RTL 支持imports/i18n/ 国际化体系与 docs/Features/Editor/RTL 相关文档如何添加依赖dependency见下文添加依赖小节与.meteor/packages、package.json直接相关阅读建议浏览这些主题时配合仓库中的 docs/DeveloperDocs/Directory-Structure.md目录结构详解与 docs/DeveloperDocs/Debugging.md调试指南一起阅读能更快建立功能 → 文件 → 集合 → 模板的映射关系。三、构建代码与提交 Pull Requestmeteor开发循环开发者文档对开发循环给出了关键说明当你启动meteor命令时它会监视 wekan 目录及其子目录中文件的变化一旦检测到代码变更就自动开始重建 bundle并在重建完成后自动刷新浏览器。这正是 Meteor 的核心开发体验。仓库中的.meteor/release文件记录当前使用的 Meteor 版本为METEOR3.5.2.meteor/packages则列出了全部 Meteor 包详见下文。此外文档还提示关注 Meteor 更新日志中提到的hot reload热重载新特性它可以让刷新更快——这也体现在 .meteor/versions 中的hot-code-push1.0.5上Meteor 经典的 HCP 机制以及现代 Meteor 的 HMRHot Module Replacement。开发者文档引用了 docs/Features/Editor/Emoji.md 的 How you could add another plugin 一节作为构建代码并提交 Pull Request的完整范例——该文档以 Markdown 编辑器添加新插件为例展示了从需求、实现到集成的一整套流程是贡献者上手的最佳样例。四、开发环境与编辑器VSCode / VSCodium开发者文档推荐使用VSCodium去除了微软跟踪代码的 VSCode 发行版并建议安装以下插件Prettier用于右键格式化 JavaScript 代码注意这与不要使用格式化工具的约定并不矛盾——Prettier 插件是供开发者按需手动格式化本地代码的而不是 CI 里强制执行的步骤其他可选插件Meteor、Jade、Stylus、Dockerfile 等语言支持插件。仓库根目录存在 .vscode/VSCode 设置与 .editorconfig跨编辑器统一编码风格说明项目同时为多种编辑器提供了基础约定。五、快速定位代码find.sh脚本这是 Wekan 贡献者最常使用的工具之一。仓库根目录的 find.sh 是一个 Bash 脚本作用是在所有子目录中查找文本同时忽略所有临时/生成目录node_modules已安装的 Node 模块.buildWekan 的发布 bundle由源码合并而成不要编辑会被删除重建.meteor具体为.meteor/local等运行时目录与.gitgit 历史。脚本签名是./find.sh text-to-find查找结果用less分页显示。文档给出的示例是cd wekan ./find.sh js-search运行后会看到.jade模板文件搜索输入框所在的模板、.js文件搜索逻辑实现以及.styl文件CSS 样式。从源码结构看脚本使用find . -type f配合多条-not -path排除规则并用grep -I跳过二进制文件。实操提示由于脚本最终通过less分页交互式终端中可用/继续搜索、q退出。这套流程非常适合回答某个功能如卡片搜索、卡片归档的代码在哪里这类问题。六、开始开发Getting Started环境与两种方式6.1 官方开发环境说明开发者文档说明Wekan 的开发主要在 Ubuntu 20.10 64bit 上进行但在任何 Debian、Ubuntu、WSL Ubuntu 20.04 上均可构建Mac 与 Windows 也有可行路径Windows 上可通过choco install -y meteor安装 Meteor然后根据提示执行meteor add ...或meteor npm install --save ...。新贡献者的入门建议浏览旧 [pull requests] 了解项目历史与代码演进阅读 Wekan 源码可使用 gitk 等 git 历史查看 GUI阅读 Meteor 官方文档 记录的 Meteor 版本METEOR3.5.2为准**其他版本信息见 Dockerfile当前基于debian:trixie构建。6.2 方式一Docker 从源码构建文档推荐的最新方式克隆 wekan/wekan 仓库更新docker-compose.yml文件中的ROOT_URL等环境变量详见仓库根目录 docker-compose.yml 中注释安装 Docker从源码构建并启动docker compose up -d --build6.3 方式二Docker 开发环境非最新方式文档还提及 wekan-dev 这个用于 Wekan 开发的 Docker 环境方案。此外docs/DeveloperDocs/Build-from-source.md 提供了从源码构建的完整分步说明docs/DeveloperDocs/Build-and-Create-Pull-Request.md 则专门讲解构建 提交 PR的组合流程两者都是本节的重要补充。6.4 仓库构建配置速览Meteor 包清单.meteor/packages 明确列出依赖构建系统ecmascript、standard-minifier-js、rspack1.3.0、modern-browsers、模板blaze3.0.2、集合aldeed:collection2、aldeed:schema-index、reywood:publish-composite、mongo、账号体系accounts-password、accounts-2fa、accounts-express以及wekan-ldap、wekan-accounts-cas、wekan-accounts-saml、wekan-accounts-sandstorm、wekan-oidc等自维护包、路由ostrio:flow-router-extra、UIostrio:i18n、wekan-markdown、wekan-fullcalendar、wekan-fontawesome与测试meteortesting:mochanpm 依赖package.json 声明了meteor.mainModule为client/main.jsserver/main.js测试模块为client/lib/tests/index.jsserver/lib/tests/index.js并包含 S3/Azure/Google Cloud 存储适配、office-open-xml-viewer、exceljs 等大量运行时依赖客户端入口client/imports.js 按固定顺序导入 i18n、共享模型、运行时服务、config、client lib、Blaze helpers 与全部client/features/*特性模块——这是理解页面加载了什么的权威清单。七、Pull Request 工作流提交前必读开发者文档对提交 PR 给出了明确规则依赖安装如果包在 Meteor 生态atmospherejs.com可用用meteor add packagename如果在 npm 可用用meteor npm install packagename。以这种方式添加即可无需在构建脚本中 clone 仓库。翻译唯一入口提交 PR 时只对英文翻译文件 imports/i18n/data/en.i18n.json 做增改。其他语言的翻译由 Transifex 平台完成仓库内 .tx 目录即 Transifex 配置文件。修复已有 PR如果你要修复某个已存在的 PR 的问题以评论comment形式添加你的修复不要新开 PR。新功能如果没有已存在的 PR才为它新建 PR。清理调试代码删除所有console.log语句。仓库源码也印证了这一约定——例如 client/features/cards.js 中console.log的数量为 0。移除不需要的提交PR 中多余/错误的提交应被清理文档给出了 rebase 清理提交的方法。八、CI 与 lintTravis 的现状与本地自查开发者文档专门提醒了一个现状注意Travis 目前是坏的总是显示诸如变量未定义或未使用之类的警告和错误所以只要你的代码能跑就忽略 Travis。这一条对新手非常重要——不要把 Travis 的红叉当作自己代码有问题的必然证据。同时贡献者仍应在本地做 lint 自查安装 ESLintnpm install eslint运行npm run lint尝试自动修复eslint --fix filename.js。仓库根目录的 .eslintrc.json 就是 ESLint 配置文件可供本地 lint 使用。文档还提到截至 2018-05-05 可能已失效jsbeautifer 网站可作为备选其设置要点是Indent with 2 spaces两个空格缩进与 JSLint-happy 风格。九、选择要解决的问题Choosing issues to work on开发者文档对选题给出了非常务实的建议自由选题你可以在任意 issue 上工作主动声明在 issue 上留言说明正在处理它并持续给出进展更新一次只做一个一次专注一个 issue做完再做下一个维护个人贡献清单把贡献记录在个人网站上形成可展示的履历记录实现耗时记录每个功能部件的实现时间据此估算类似功能的工作量并事后复盘改进估算方法雇主看重有可验证记录的开发者关于设置项位置通常功能需求已经定义得足够清晰把新的 Settings 选项放在你认为最符合逻辑的位置即可。此外文档强调对评论你代码的人保持友善并吸收那些最有意义的建议。十、构建管线Build PipelineJADE Stylus Blaze mutation 模式这是理解 Wekan 技术栈最关键的一节也是与传统 Meteor 应用差异最大之处10.1 模板JADE 而非 HTML模板使用 JADE 编写而不是纯 HTML仓库 client/components/ 下共 129 个.jade文件重要规则来自 docs/DeveloperDocs/Directory-Structure.md.jade文件放在磁盘上并不会被自动加载每个模板都必须由 client/features/*.js 按名称导入组件.js若被其他组件 import也必须 import 它自己的.jade。测试 tests/templateRegistration.test.cjs 专门校验每个client/components下的.jade都被导入、每个template都解析到已导入的模板——这正是历史上headerBarControls.jade因未被导入而在 All Boards 页面渲染时报 No such template 的教训。10.2 样式Stylus 预编译器CSS 使用 Stylus 预编译器编写.styl源文件最终编译为 CSSfind.sh搜索样式时找的正是.styl文件。10.3 模板体系BlazeLayoutMeteor 模板以BlazeLayout模板方式创建通过 config/router.js 中的 FlowRouter仓库实际使用ostrio:flow-router-extra见 .meteor/packages进行客户端路由账号相关 UI 使用 AccountsTemplates配置在 config/accounts.js。10.4 数据写权限mutations 取代 allow/deny这是 Wekan 架构上最有辨识度的设计项目中定义的大量collections不使用 allow/deny 范式而是使用mutations来定义允许进行哪些操作。从源码结构看这一模式在 models/ 目录中体现得最为彻底每个模型文件如 models/boards.js、models/cards.js、models/lists.js、models/checklists.js不仅定义集合与 SimpleSchema 校验还承载 helpers、mutations、methods、hooks 与引导代码服务端另以 JSON REST API 形式提供接口见 server/apiMiddleware.js 与 openapi/ 下的 API 描述。mutation 模式把允许什么操作显式编码在模型层替代了分散的 allow/deny 规则。10.5 进一步学习路径文档建议查看 Wiki 中的 feature summaries仍在完善中否则就翻阅 git 历史看旧功能是怎么构建的并特别推荐了 Start and Due date开始与截止日期功能的 PR 作为范例。对应地当前仓库中 models/cards.js 的日期字段、client/components/cards/cardDate.jade 与cardDate.js正是该功能的现成实现可以直接研读。十一、国际化Translations新功能必须支持 i18n开发者文档明确要求如果添加新功能请同时支持内置的国际化internationalization能力。具体机制在仓库中非常清晰imports/i18n/ 目录存放 i18n 基础设施index.js、languages.js、moment.js、tap.js、loadHelpers.js等imports/i18n/data/ 下每个受支持语言对应一个*.i18n.json文件当前仓库共 246 个语言文件如en.i18n.json、zh_CN.i18n.json等PR 只改英文源文件en.i18n.json其他语言在 Transifex 平台协作翻译仓库 releases/translations/ 下有拉取 Transifex 翻译并逐 key 合并绝不覆盖人工翻译的工具脚本。因此贡献新功能时的国际化落地路径是在 imports/i18n/data/en.i18n.json 中添加英文 key 与默认文案然后在代码中通过 i18n 辅助函数引用该 key。十二、从 Trello 导入Export From TrelloWekan 支持从 Trello 导入现有看板。仓库中的对应实现包括models/import.js实现importBoard()方法models/trelloCreator.jsTrello 导入的板/列表/卡片重建逻辑models/wekanCreator.jsWekan 自身格式的导入客户端导入界面模板client/components/import/import.jade配套 trelloMembersMapper.js 与 wekanMembersMapper.js 完成成员映射测试侧tests/durableTrelloImport.test.cjs 覆盖 Trello 导入的持久性。十三、目录结构速查与进一步阅读开发者文档将目录结构详述单独成篇docs/DeveloperDocs/Directory-Structure.md。其中一张总表把整个仓库 20 个目录一网打尽最值得记住的几点目录内容关键约束client/浏览器端运行的 Blaze 组件、样式、客户端库.jade必须被 client/features 导入server/仅服务端startup、publications、methods、REST 路由、lib/客户端不可见models/集合、schema、helpers、mutations前后端共享绝不能 importserver/会破坏客户端构建服务端逻辑放在Meteor.isServer或server/lib/imports/i18n、响应式缓存、共享 SimpleSchema、startup非模型非组件的共享代码packages/自维护的 Meteor 包CAS、LDAP、OIDC、Sandstorm、lockout、markdown—config/路由FlowRouter与账号配置—migrations/数据库迁移每个迁移一个文件启动时按序执行schema 非向后兼容变更时必须写迁移tests/*.test.cjs由tests/run-node-suites.cjs运行 Playwright e2e许多测试直接读源码来钉住行为补充两个易混淆点同样来自 Directory-Structure.md.build/是发布 bundlemeteor build .build --directory的产物而_build/是 rspack 的编译输出——任何 Meteor 编译dev 运行、测试、发布构建都会写它是交接产物而非残留_build/已被 gitignore但绝不能加入.meteorignore否则会直接破坏构建。十四、交流渠道与后续学习开发者文档最后指向了 Wekan 社区聊天渠道并提示在开始任何重要贡献前阅读 Meteor 风格指南。结合本仓库推荐的完整学习路径是通读本文涉及的 Developer-Documentation.md精读 Directory-Structure.md 建立全局认知按 Build-from-source.md 与 Build-and-Create-Pull-Request.md 实操本地构建用./find.sh从一个小功能如卡片搜索、自定义字段切入源码用 Debugging.md 中的方法排障遵循本文的 PR 工作流提交贡献。十五、开发与贡献核心要点速查表事项结论代码风格遵循 Meteor Style Guide不要用 Prettier/ESLint 强行格式化Meteor 版本METEOR3.5.2见 .meteor/release本地构建meteor命令启动开发循环改动自动重建并刷新浏览器Docker 方式docker compose up -d --build找代码./find.sh keyword忽略 node_modules/.build/.meteor/.git翻译PR 只改 imports/i18n/data/en.i18n.jsonlintnpm run lint、eslint --fixTravis 状态视为仅供参考提交 PR修旧 PR 用评论、新功能开新 PR、删除所有console.log模板/样式JADE Stylus BlazeLayout.jade必须显式导入数据写权限使用 models 层的 mutation 模式而非 allow/deny以上内容均以当前仓库实际文件为准可作为新贡献者快速上手的第一份地图。【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
