指南：GJS + GTK4/Libadwaita 電子書閱讀器的代碼規(guī)范、工作流與本地化協(xié)作)
桌面應用【免費下載鏈接】foliateRead e-books in style項目地址https://gitcode.com/gh_mirrors/fo/foliate點擊查看免費下載本文圍繞開源倉庫 CONTRIBUTING.md 展開系統(tǒng)講解 Foliate一款基于 GJS 與 GTK4/Libadwaita 的電子書閱讀器的貢獻開發(fā)全流程從開發(fā)環(huán)境搭建、代碼風格與 ESLint 規(guī)則、Issue/PR 工作流到基于po/目錄的本地化翻譯協(xié)作。讀完本文你將掌握如何在本地編譯運行 Foliate、寫出符合項目規(guī)范的 GJS 代碼、提交一份整潔的 Pull Request并參與多語言翻譯。一、項目技術棧與貢獻者須知Foliate 是使用GJSGNOME JavaScript 綁定 GTK4 Libadwaita構建的 GTK 應用渲染層依賴WebKitGTK 6.0書籍內容在 WebView 中呈現。這意味著貢獻者必須熟悉現代 JavaScriptES6在 GNOME 平臺上的開發(fā)模式而不是傳統(tǒng)的 C 語言 GTK 開發(fā)方式。從 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二、首次開發(fā)環(huán)境搭建與依賴安裝CONTRIBUTING.md 明確指出搭建開發(fā)環(huán)境前需要先安裝以下核心依賴依賴說明gjsGNOME 的 JavaScript 運行時Foliate 的全部業(yè)務邏輯由其執(zhí)行gtk4/libadwaita界面工具包與 Adwaita 風格庫webkitgtk-6.0WebKitGTK 6.0用于渲染 EPUB 等書籍內容結合 README.md 可以補全版本要求與各發(fā)行版的包名差異運行時要求gjs 1.82、gtk4 4.12、libadwaita 1.8Debian 系對應gir1.2-adw-1、webkitgtk-6.0Fedora 包名為webkitgtk6.0Debian 系為gir1.2-webkit-6.0。另有三個可選依賴連字符斷詞安裝 hyphenation 規(guī)則包如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再通過環(huán)境變量指定 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三、代碼風格與規(guī)范保持代碼庫一致性的硬性要求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它是上述規(guī)范的可執(zhí)行版本值得逐條對照規(guī)則配置值含義semi[error, never]禁止行尾分號錯誤級別indent[warn, 4, ...]強制 4 空格縮進警告級別quotes[warn, single]優(yōu)先使用單引號允許必要的轉義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 特有的只讀全局對象。開發(fā)依賴eslint/js、globals記錄在 package.json 中可通過npm install安裝后運行npx eslint自查。四、工作流如何高效地報告問題與提交改動4.1 報告 Bug 與開啟 Issue先搜索打開 Issue 前先確認問題是否已被報告。項目維護者強烈建議先閱讀 docs/faq.md 和 docs/troubleshooting.md——你的問題可能已有文檔化的解決方案或變通方法。信息具體提供操作系統(tǒng)版本、Foliate 版本Flatpak / 倉庫構建等來源以及可復現步驟。快速獲取調試信息打開應用主菜單進入About關于 Troubleshooting Debugging Information點擊Copy Text即可一鍵復制系統(tǒng)和版本信息。這套調試信息導出機制在源碼中真實存在Adw.AboutDialog的debug_info屬性由getDebugInfo()生成見 src/app.js 與 src/app.js其中包含操作系統(tǒng)名稱與版本、桌面環(huán)境與會話類型XDG_CURRENT_DESKTOP、XDG_SESSION_DESKTOP、XDG_SESSION_TYPE、語言環(huán)境LANG、Foliate/GJS/GTK/Adwaita/GLib/WebKitGTK 各組件版本號以及用戶數據/緩存目錄極大方便了問題定位。附帶日志如果應用崩潰請在終端中運行com.github.johnfactotum.FoliateFlatpak 環(huán)境并附上輸出。4.2 提交功能或修復Fork 并創(chuàng)建分支分支名要具描述性例如fix/sidebar-overlap或feat/custom-fonts用前綴區(qū)分修復與功能提交信息使用清晰、祈使語態(tài)的寫法如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 生態(tài)其余項目的譯法保持一致。源碼中的可翻譯字符串通過 gettext 的_()包裝例如 src/app.js 中關于對話框的標題、注釋等translator-credits用于在關于對話框中展示譯者名單。5.2 測試翻譯編譯項目后即可在界面中查看翻譯效果字符串的收集清單定義在 po/POTFILES構建腳本見 po/meson.build。翻譯文件在構建時通過i18n模塊處理提交翻譯前建議本地完整跑一次構建確認無語法錯誤且譯文在 UI 中顯示正常。六、綜合自檢清單提交 PR 前對照以下清單逐項確認代碼通過npx eslint規(guī)則見 eslint.config.js無注釋掉的代碼塊無console.log縮進與命名4 空格縮進類用 PascalCase、變量/函數用 camelCase.ui文件 ID 命名有意義提交分支名與提交信息清晰、祈使語態(tài)、一個 PR 一個主題文檔涉及的行為變化已同步更新 docs/faq.md 或 docs/troubleshooting.md本地化新 UI 字符串已接入 gettext_()包裝相關語言的.po文件已更新。遵循上述規(guī)范你的貢獻將順利融入這個 GJS GTK4/Libadwaita 生態(tài)的優(yōu)秀開源電子書閱讀器。贊分享桌面應用【免費下載鏈接】foliateRead e-books in style項目地址https://gitcode.com/gh_mirrors/fo/foliate點擊查看免費下載相關推薦3個技巧輕松解決多平臺資源下載難題3個技巧輕松解決多平臺資源下載難題 你是否遇到過這樣的情況在微信視頻號看到精彩內容卻無法保存刷到喜歡的抖音視頻但帶著煩人的水印或者在小紅書發(fā)現精美圖片卻桌面應用網絡音視頻Shotgun Code社區(qū)貢獻如何參與開源項目并提交代碼Shotgun Code社區(qū)貢獻如何參與開源項目并提交代碼 Shotgun Code作為一款為大語言模型工作流提供一鍵代碼庫爆破功能的開源工具歡迎每一位FFmpeg-Builds協(xié)作開發(fā)多人貢獻編譯腳本的工作流與規(guī)范FFmpeg Builds協(xié)作開發(fā)多人貢獻編譯腳本的工作流與規(guī)范 引言協(xié)作開發(fā)的挑戰(zhàn)與解決方案 你是否曾在多人協(xié)作編譯FFmpeg時遭遇腳本沖突、依賴版本混構建工具CI/CDDevOps開發(fā)工具上一篇編譯時元對象生成Verdigris constexpr黑科技原理解析下一篇CANN/asc-devkit L1緩沖初始化API創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Foliate 貢獻開發(fā)指南：GJS + GTK4/Libadwaita 電子書閱讀器的代碼規(guī)范、工作流與本地化協(xié)作
桌面應用【免費下載鏈接】foliateRead e-books in style項目地址https://gitcode.com/gh_mirrors/fo/foliate點擊查看免費下載本文圍繞開源倉庫 CONTRIBUTING.md 展開系統(tǒng)講解 Foliate一款基于 GJS 與 GTK4/Libadwaita 的電子書閱讀器的貢獻開發(fā)全流程從開發(fā)環(huán)境搭建、代碼風格與 ESLint 規(guī)則、Issue/PR 工作流到基于po/目錄的本地化翻譯協(xié)作。讀完本文你將掌握如何在本地編譯運行 Foliate、寫出符合項目規(guī)范的 GJS 代碼、提交一份整潔的 Pull Request并參與多語言翻譯。一、項目技術棧與貢獻者須知Foliate 是使用GJSGNOME JavaScript 綁定 GTK4 Libadwaita構建的 GTK 應用渲染層依賴WebKitGTK 6.0書籍內容在 WebView 中呈現。這意味著貢獻者必須熟悉現代 JavaScriptES6在 GNOME 平臺上的開發(fā)模式而不是傳統(tǒng)的 C 語言 GTK 開發(fā)方式。從 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二、首次開發(fā)環(huán)境搭建與依賴安裝CONTRIBUTING.md 明確指出搭建開發(fā)環(huán)境前需要先安裝以下核心依賴依賴說明gjsGNOME 的 JavaScript 運行時Foliate 的全部業(yè)務邏輯由其執(zhí)行gtk4/libadwaita界面工具包與 Adwaita 風格庫webkitgtk-6.0WebKitGTK 6.0用于渲染 EPUB 等書籍內容結合 README.md 可以補全版本要求與各發(fā)行版的包名差異運行時要求gjs 1.82、gtk4 4.12、libadwaita 1.8Debian 系對應gir1.2-adw-1、webkitgtk-6.0Fedora 包名為webkitgtk6.0Debian 系為gir1.2-webkit-6.0。另有三個可選依賴連字符斷詞安裝 hyphenation 規(guī)則包如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再通過環(huán)境變量指定 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三、代碼風格與規(guī)范保持代碼庫一致性的硬性要求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它是上述規(guī)范的可執(zhí)行版本值得逐條對照規(guī)則配置值含義semi[error, never]禁止行尾分號錯誤級別indent[warn, 4, ...]強制 4 空格縮進警告級別quotes[warn, single]優(yōu)先使用單引號允許必要的轉義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 特有的只讀全局對象。開發(fā)依賴eslint/js、globals記錄在 package.json 中可通過npm install安裝后運行npx eslint自查。四、工作流如何高效地報告問題與提交改動4.1 報告 Bug 與開啟 Issue先搜索打開 Issue 前先確認問題是否已被報告。項目維護者強烈建議先閱讀 docs/faq.md 和 docs/troubleshooting.md——你的問題可能已有文檔化的解決方案或變通方法。信息具體提供操作系統(tǒng)版本、Foliate 版本Flatpak / 倉庫構建等來源以及可復現步驟。快速獲取調試信息打開應用主菜單進入About關于 Troubleshooting Debugging Information點擊Copy Text即可一鍵復制系統(tǒng)和版本信息。這套調試信息導出機制在源碼中真實存在Adw.AboutDialog的debug_info屬性由getDebugInfo()生成見 src/app.js 與 src/app.js其中包含操作系統(tǒng)名稱與版本、桌面環(huán)境與會話類型XDG_CURRENT_DESKTOP、XDG_SESSION_DESKTOP、XDG_SESSION_TYPE、語言環(huán)境LANG、Foliate/GJS/GTK/Adwaita/GLib/WebKitGTK 各組件版本號以及用戶數據/緩存目錄極大方便了問題定位。附帶日志如果應用崩潰請在終端中運行com.github.johnfactotum.FoliateFlatpak 環(huán)境并附上輸出。4.2 提交功能或修復Fork 并創(chuàng)建分支分支名要具描述性例如fix/sidebar-overlap或feat/custom-fonts用前綴區(qū)分修復與功能提交信息使用清晰、祈使語態(tài)的寫法如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 生態(tài)其余項目的譯法保持一致。源碼中的可翻譯字符串通過 gettext 的_()包裝例如 src/app.js 中關于對話框的標題、注釋等translator-credits用于在關于對話框中展示譯者名單。5.2 測試翻譯編譯項目后即可在界面中查看翻譯效果字符串的收集清單定義在 po/POTFILES構建腳本見 po/meson.build。翻譯文件在構建時通過i18n模塊處理提交翻譯前建議本地完整跑一次構建確認無語法錯誤且譯文在 UI 中顯示正常。六、綜合自檢清單提交 PR 前對照以下清單逐項確認代碼通過npx eslint規(guī)則見 eslint.config.js無注釋掉的代碼塊無console.log縮進與命名4 空格縮進類用 PascalCase、變量/函數用 camelCase.ui文件 ID 命名有意義提交分支名與提交信息清晰、祈使語態(tài)、一個 PR 一個主題文檔涉及的行為變化已同步更新 docs/faq.md 或 docs/troubleshooting.md本地化新 UI 字符串已接入 gettext_()包裝相關語言的.po文件已更新。遵循上述規(guī)范你的貢獻將順利融入這個 GJS GTK4/Libadwaita 生態(tài)的優(yōu)秀開源電子書閱讀器。贊分享桌面應用【免費下載鏈接】foliateRead e-books in style項目地址https://gitcode.com/gh_mirrors/fo/foliate點擊查看免費下載相關推薦3個技巧輕松解決多平臺資源下載難題3個技巧輕松解決多平臺資源下載難題 你是否遇到過這樣的情況在微信視頻號看到精彩內容卻無法保存刷到喜歡的抖音視頻但帶著煩人的水印或者在小紅書發(fā)現精美圖片卻桌面應用網絡音視頻Shotgun Code社區(qū)貢獻如何參與開源項目并提交代碼Shotgun Code社區(qū)貢獻如何參與開源項目并提交代碼 Shotgun Code作為一款為大語言模型工作流提供一鍵代碼庫爆破功能的開源工具歡迎每一位FFmpeg-Builds協(xié)作開發(fā)多人貢獻編譯腳本的工作流與規(guī)范FFmpeg Builds協(xié)作開發(fā)多人貢獻編譯腳本的工作流與規(guī)范 引言協(xié)作開發(fā)的挑戰(zhàn)與解決方案 你是否曾在多人協(xié)作編譯FFmpeg時遭遇腳本沖突、依賴版本混構建工具CI/CDDevOps開發(fā)工具上一篇編譯時元對象生成Verdigris constexpr黑科技原理解析下一篇CANN/asc-devkit L1緩沖初始化API創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考