Foliate 贡献开发指南：GJS + GTK4/Libadwaita 电子书阅读器的代码规范、工作流与本地化协作

桌面应用【免费下载链接】foliateRead e-books in style项目地址https://gitcode.com/gh_mirrors/fo/foliate点击查看免费下载本文围绕开源仓库 CONTRIBUTING.md 展开系统讲解 Foliate一款基于 GJS 与 GTK4/Libadwaita 的电子书阅读器的贡献开发全流程从开发环境搭建、代码风格与 ESLint 规则、Issue/PR 工作流到基于po/目录的本地化翻译协作。读完本文你将掌握如何在本地编译运行 Foliate、写出符合项目规范的 GJS 代码、提交一份整洁的 Pull Request并参与多语言翻译。一、项目技术栈与贡献者须知Foliate 是使用GJSGNOME JavaScript 绑定 GTK4 Libadwaita构建的 GTK 应用渲染层依赖WebKitGTK 6.0书籍内容在 WebView 中呈现。这意味着贡献者必须熟悉现代 JavaScriptES6在 GNOME 平台上的开发模式而不是传统的 C 语言 GTK 开发方式。从 meson.build 可以看到项目的构建基线meson_version: 0.59.0当前项目版本为3.3.0并可通过check_runtime_deps选项在配置阶段校验运行时依赖的最低版本if get_option(check_runtime_deps) dependency(gjs-1.0, version: 1.82) dependency(gtk4, version: 4.12) dependency(libadwaita-1, version: 1.8) dependency(webkitgtk-6.0, version: 2.40.1) endif二、首次开发环境搭建与依赖安装CONTRIBUTING.md 明确指出搭建开发环境前需要先安装以下核心依赖依赖说明gjsGNOME 的 JavaScript 运行时Foliate 的全部业务逻辑由其执行gtk4/libadwaita界面工具包与 Adwaita 风格库webkitgtk-6.0WebKitGTK 6.0用于渲染 EPUB 等书籍内容结合 README.md 可以补全版本要求与各发行版的包名差异运行时要求gjs 1.82、gtk4 4.12、libadwaita 1.8Debian 系对应gir1.2-adw-1、webkitgtk-6.0Fedora 包名为webkitgtk6.0Debian 系为gir1.2-webkit-6.0。另有三个可选依赖连字符断词安装 hyphenation 规则包如hyphen-en、hyphen-fr用于自动断词排版文本转语音安装speech-dispatcher及输出模块如espeak-ng文件追踪安装tracker 3Debian 系gir1.2-tracker-3.0与tracker-miners用于追踪电子书文件位置。2.1 获取源码仓库使用git submodulessrc/foliate-js是捆绑的第三方 JS 库克隆时必须递归拉取子模块git clone --recurse-submodules https://github.com/johnfactotum/foliate.git也可以直接从 Releases 页面下载.tar.xz源码包。2.2 不构建直接运行快速试运行或验证小改动无需完整构建gjs -m src/main.js注意这种方式不会加载 GSettings schema设置不会持久化保存。解决方法是先用glib-compile-schemas编译 data/com.github.johnfactotum.Foliate.gschema.xml再通过环境变量指定 schema 目录启动glib-compile-schemas data GSETTINGS_SCHEMA_DIRdata gjs -m src/main.js2.3 Meson 构建与安装构建期还需要meson ( 0.59)、pkg-config、gettextmeson setup build sudo ninja -C build install卸载使用sudo ninja -C build uninstall。若想免 root 安装到本地目录可指定自定义 prefixmeson setup build --prefix $PWD/run ninja -C build install GSETTINGS_SCHEMA_DIRrun/share/glib-2.0/schemas ./run/bin/foliate三、代码风格与规范保持代码库一致性的硬性要求CONTRIBUTING.md 强调 Consistency is key to keeping the codebase maintainable。作为 GJS GTK4/Libadwaita 项目Foliate 的代码风格原则如下语言使用现代 JavaScriptES6尽量避免遗留语法缩进使用4 个空格禁止 Tab命名约定类与 GNOME 组件使用PascalCase如源码中的Adw.Application子类FoliateApplication见 src/app.js变量与函数使用camelCasesnake_case 一般避免使用除非是与特定 GLib/GObject 属性交互所必需干净的 PR提交前必须通过 lint且不允许遗留被注释掉的代码块或console.log语句UI 文件编辑.uiXML文件时保持结构整洁ID 命名要能体现组件用途可参考 src/ui/ 下如book-viewer.ui、library.ui的命名习惯。3.1 ESLint 配置的实际约束项目的 ESLint 配置位于 eslint.config.js它是上述规范的可执行版本值得逐条对照规则配置值含义semi[error, never]禁止行尾分号错误级别indent[warn, 4, ...]强制 4 空格缩进警告级别quotes[warn, single]优先使用单引号允许必要的转义comma-dangle[warn, always-multiline]多行时要求尾逗号no-trailing-spaceswarn禁止行尾空白no-unused-varswarn禁止未使用变量no-console[warn, { allow: [...] }]仅允许debug/warn/error/assert普通console.log属于警告项no-constant-conditionerror禁止恒定条件no-empty[error, { allowEmptyCatch: true }]禁止空代码块空 catch 除外其中ignores: [src/foliate-js]表明捆绑的第三方库不参与 lintglobals声明了imports与pkg这两个 GJS 特有的只读全局对象。开发依赖eslint/js、globals记录在 package.json 中可通过npm install安装后运行npx eslint自查。四、工作流如何高效地报告问题与提交改动4.1 报告 Bug 与开启 Issue先搜索打开 Issue 前先确认问题是否已被报告。项目维护者强烈建议先阅读 docs/faq.md 和 docs/troubleshooting.md——你的问题可能已有文档化的解决方案或变通方法。信息具体提供操作系统版本、Foliate 版本Flatpak / 仓库构建等来源以及可复现步骤。快速获取调试信息打开应用主菜单进入About关于 Troubleshooting Debugging Information点击Copy Text即可一键复制系统和版本信息。这套调试信息导出机制在源码中真实存在Adw.AboutDialog的debug_info属性由getDebugInfo()生成见 src/app.js 与 src/app.js其中包含操作系统名称与版本、桌面环境与会话类型XDG_CURRENT_DESKTOP、XDG_SESSION_DESKTOP、XDG_SESSION_TYPE、语言环境LANG、Foliate/GJS/GTK/Adwaita/GLib/WebKitGTK 各组件版本号以及用户数据/缓存目录极大方便了问题定位。附带日志如果应用崩溃请在终端中运行com.github.johnfactotum.FoliateFlatpak 环境并附上输出。4.2 提交功能或修复Fork 并创建分支分支名要具描述性例如fix/sidebar-overlap或feat/custom-fonts用前缀区分修复与功能提交信息使用清晰、祈使语态的写法如Add support for OPDS catalogs而不是I fixed some stuff一个 PR 只做一件事保持 Pull Request 聚焦两个无关的修复请拆成两个独立 PR。五、翻译指南让 Foliate 覆盖更多语言Foliate 的目标是让每个语言的使用者都能无障碍使用。本地化工作基于GNU gettext体系全部翻译文件位于po/目录。5.1 工作方式工具使用 Poedit 或直接手动编辑.po文件查找语言文件在 po/ 目录下找到你的语言文件例如pt_BR.po仓库当前已收录包括zh_CN.po、zh_TW.po、ja.po、ko.po在内的 30 种语言初始化新语言如果po/中没有你的语言可从foliate.pot模板初始化msginit --locale你的语言代码 --inputpo/com.github.johnfactotum.Foliate.pot可用的语言代码清单见 po/LINGUAS术语一致性确保 Metadata、E-book 等技术术语与 GNOME 生态其余项目的译法保持一致。源码中的可翻译字符串通过 gettext 的_()包装例如 src/app.js 中关于对话框的标题、注释等translator-credits用于在关于对话框中展示译者名单。5.2 测试翻译编译项目后即可在界面中查看翻译效果字符串的收集清单定义在 po/POTFILES构建脚本见 po/meson.build。翻译文件在构建时通过i18n模块处理提交翻译前建议本地完整跑一次构建确认无语法错误且译文在 UI 中显示正常。六、综合自检清单提交 PR 前对照以下清单逐项确认代码通过npx eslint规则见 eslint.config.js无注释掉的代码块无console.log缩进与命名4 空格缩进类用 PascalCase、变量/函数用 camelCase.ui文件 ID 命名有意义提交分支名与提交信息清晰、祈使语态、一个 PR 一个主题文档涉及的行为变化已同步更新 docs/faq.md 或 docs/troubleshooting.md本地化新 UI 字符串已接入 gettext_()包装相关语言的.po文件已更新。遵循上述规范你的贡献将顺利融入这个 GJS GTK4/Libadwaita 生态的优秀开源电子书阅读器。赞分享桌面应用【免费下载链接】foliateRead e-books in style项目地址https://gitcode.com/gh_mirrors/fo/foliate点击查看免费下载相关推荐3个技巧轻松解决多平台资源下载难题3个技巧轻松解决多平台资源下载难题 你是否遇到过这样的情况在微信视频号看到精彩内容却无法保存刷到喜欢的抖音视频但带着烦人的水印或者在小红书发现精美图片却桌面应用网络音视频Shotgun Code社区贡献如何参与开源项目并提交代码Shotgun Code社区贡献如何参与开源项目并提交代码 Shotgun Code作为一款为大语言模型工作流提供一键代码库爆破功能的开源工具欢迎每一位FFmpeg-Builds协作开发多人贡献编译脚本的工作流与规范FFmpeg Builds协作开发多人贡献编译脚本的工作流与规范 引言协作开发的挑战与解决方案 你是否曾在多人协作编译FFmpeg时遭遇脚本冲突、依赖版本混构建工具CI/CDDevOps开发工具上一篇编译时元对象生成Verdigris constexpr黑科技原理解析下一篇CANN/asc-devkit L1缓冲初始化API创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考