本指南涵蓋您如何參與 Quasar 持續開發的方法。

但是，在我們開始之前，先說明一個重要的注意事項。每位與 Quasar 互動的人都應遵守 Quasar 行為準則。

既然我們已經說明了這一點，就讓我們開始吧！

閱讀本指南後，您將了解

• 如何使用 GitHub 回報問題。
• 如何複製儲存庫並執行測試套件。
• 如何協助解決現有問題。
• 如何貢獻 Quasar 文件。
• 如何建立 Quasar App Extension。
• 如何貢獻 Quasar 原始碼。

Quasar 不是「別人的框架」。許多人為 Quasar 做出貢獻，從單個字元到大規模架構變更或重要的文件——所有這些都旨在讓 Quasar 對每個人都更好。即使您還沒有準備好編寫程式碼或文件，您也可以透過多種其他方式做出貢獻，從回報問題到測試修補程式。

協助支援

最簡單的貢獻方式之一是在我們不同的問答系統中回答問題。成為 Quasar 社群中樂於助人且積極的成員，回答您知道答案的問題，甚至加入您最好的猜測。參與此類討論也可能是一個很好的學習經驗。這是一個雙贏的局面！

以下是我們的討論/問答場所

• GitHub 討論區：一個提問和獲取有關 Quasar 及其生態系統的答案的地方。這也是與他人分享您的知識和經驗的好地方。您也可以使用它來分享您的想法和功能請求。
• Discord 伺服器：Quasar 開發人員即時會面和聊天的場所。您可以提出問題、分享您的知識並幫助他人。也可以在那裡發布職位空缺或尋找工作。

分享（和建立）您的經驗

除了在論壇和聊天中回答問題和分享資源外，還有其他一些不太明顯的方式可以分享和擴展您所知道的

• 開發學習材料。人們常說，學習的最佳方式是教學。如果您正在使用 Quasar 做一些有趣的事情，請透過撰寫部落格文章、開發工作坊，甚至發布您在社群媒體上分享的 gist 來增強您的專業知識。
• 分享您的技術堆疊。向其他人展示哪些技術經過充分測試並且可以與 Quasar 整合。宣傳您的專案並填寫您最喜歡的基於 Quasar 的堆疊。請務必提及 @Quasarframework 和所有其他相關技術。
• 關注您關心的儲存庫。每當該儲存庫中有活動時，這都會向您發送通知，讓您了解正在進行的討論和即將推出的功能。這是建立專業知識的絕佳方式，以便您最終能夠幫助解決問題和提取請求。

回報問題

• GitHub：如果您想建立錯誤報告或文件報告，那就是 GitHub issues 的用途。確保您選擇正確的範本並在建立問題時遵循給定的指示。

如果您在 Quasar 中發現了問題，但不是安全風險，請在 GitHub 上的Issues下搜尋，以檢查問題是否已得到解答，甚至在開發分支 (dev) 中已修復。

• 主要儲存庫的問題列表專門用於錯誤報告和文件報告。不符合規定的問題將立即關閉。

  • 對於簡單的初學者問題，您可以從Quasar Discord 聊天中獲得快速解答。

  • 對於更複雜的問題，您可以使用「討論」部分。在提出問題時，請務必提供足夠的資訊——這會讓其他人更容易幫助您！

  • 對於功能請求，您可以開始新的功能討論。

• 嘗試搜尋您的問題，它可能已經在開發分支 (dev) 中得到解答或甚至已修復。

• 檢查問題是否可以在最新穩定版本的 Quasar 上重現。請務必註明您正在使用的特定版本。

• 您必須清楚地描述重現您遇到的問題所需的步驟。儘管我們很樂意盡可能地幫助我們的使用者，但在沒有明確的重現步驟的情況下診斷問題非常耗時且根本不可持續。

• 僅使用重現意外行為所需的最少程式碼量。一份好的錯誤報告應隔離顯示意外行為的特定方法，並精確定義如何違反預期。您期望該方法或這些方法做什麼，觀察到的行為有何不同？您越精確地隔離問題，我們就能越快地調查。

• 沒有明確重現步驟的問題將不會被分類。如果標記為「bug/0-needs-info」的問題在相當長的一段時間內沒有收到問題作者的進一步輸入，則該問題將被關閉。

• 如果您的問題已解決但仍處於開啟狀態，請隨時關閉它。如果您自己找到了解決方案，則解釋您是如何修復它的可能會有所幫助。

• 最重要的是，我們懇請您耐心等待：團隊必須在您的請求與許多其他責任之間取得平衡——修復其他錯誤、回答其他問題、新功能、新文件等等。問題列表不是付費支援，我們無法保證您的問題可以多快解決，儘管我們已盡力做到最好。

協助解決現有問題

作為回報問題之外的下一步，您可以透過提供有關問題的回饋來幫助 Quasar 團隊解決現有問題。如果您是 Quasar 開發新手，這可能是邁出第一步的好方法，您將熟悉程式碼庫和流程。

如果您查看 GitHub Issues 中的問題列表，您會發現許多問題已經需要關注。您可以為這些做些什麼？實際上相當多

驗證錯誤報告

首先，驗證錯誤報告很有幫助。您可以在自己的電腦上重現回報的問題嗎？如果是這樣，您可以向問題新增評論，說明您也看到了同樣的情況。

如果問題非常模糊，您可以幫助將其縮小到更具體的範圍嗎？也許您可以提供更多資訊來幫助重現錯誤，或透過消除不必要的步驟來幫助證明問題。

無論您最終是否自己編寫程式碼，您所做的任何使錯誤報告更簡潔或更易於重現的事情都有助於人們嘗試編寫程式碼來修復這些錯誤。

測試修補程式

您也可以透過檢查已透過 GitHub 提交給 Quasar 的提取請求來提供幫助。為了應用別人的變更，您需要先建立一個專用分支

$ git checkout -b testing_branch

然後，您可以使用他們的遠端分支來更新您的程式碼庫。例如，假設 GitHub 使用者 JohnSmith 已 fork 並推送到了位於 https://github.com/JohnSmith/quasar 的主題分支「orange」。

$ git remote add JohnSmith https://github.com/JohnSmith/quasar.git
$ git pull JohnSmith orange

應用他們的分支後，測試一下！以下是一些需要思考的事情

• 變更是否真的有效？
• 它是否具有適當的文件涵蓋範圍？其他地方的文件是否應更新？
• 您喜歡此實作方式嗎？您能想到更好或更快的方法來實作他們變更的一部分嗎？

一旦您確信提取請求包含良好的變更，請在 GitHub issue 上評論以表示您的同意。您的評論應表明您喜歡該變更以及您喜歡它的原因。類似於

如果您的評論只是「+1」，那麼其他審閱者很可能不會太認真對待它。表明您花時間審閱了提取請求。

貢獻 Quasar 文件

您可以透過使 Quasar 文件更連貫、一致或可讀，新增遺失的資訊、更正事實錯誤、修復錯字或使其與最新的 edge Quasar 同步來幫助改進 Quasar 文件。

對於較大的編輯，請變更 Quasar 原始檔（位於 GitHub 上的此處）。

文件最佳實務

隨著時間的推移，我們整合了一套我們遵循的規則，遵循這些規則將加快合併過程

• 標題大寫，請參閱「How to Use Capitalize My Title」。
• 使用現在式。
• 簡潔明瞭，避免文字/程式碼重複。
• 連結到用作主要資訊來源且通常更新頻率更高的外部來源，例如 Mozilla MDN、Vue.js API，而不是很快就會過時的編譯教學課程。
• 在開啟 PR 之前進行校對
• 請勿重複來自其他來源的文字，僅保留與 Quasar 相關且在上下文中顯示特定功能的內容
• 使用官方名稱。例如，使用 Firebase 而不是 firebase
• 從 PR 中排除所有草稿和未完成的頁面

Fork (分支)

導航至 Quasar GitHub 儲存庫，然後按下右上角的 “Fork (分支)”。

Clone (複製) fork (分支) 的儲存庫

為了能夠更改文件，您需要 clone (複製) fork (分支) 的儲存庫

$ git clone https://github.com/your-user-name/quasar.git
$ cd quasar
$ git checkout dev

安裝 dependencies (依賴)

安裝所需的 dependencies (依賴)。

$ pnpm i

針對您的本地儲存庫執行文件

$ cd docs
$ pnpm dev

文件會針對您本地 clone (複製) 的儲存庫執行。

在本地編輯和測試您的更改

Commit (提交) 您的更改

當您對電腦上的變更感到滿意時，您需要將更改 commit (提交) 到 Git

$ git commit -a

這應該會啟動您的編輯器來撰寫 commit (提交) 訊息。完成後，儲存並關閉以繼續。

更新您的本地儲存庫

很可能在您工作時，master 分支已發生其他變更。去取得它們。

1. 新增一個遠端 Quasar 儲存庫作為 upstream (上游)

$ git remote add upstream https://github.com/quasarframework/quasar.git

2. Fetch (抓取) 所有遠端分支

$ git fetch upstream

3. Checkout (切換) 到您 fork (分支) 的本地 dev 分支。

$ git checkout dev
> Switched to branch 'dev'

4. 將來自 upstream/dev 的變更 merge (合併) 到您的本地 dev 分支中。這會使您 fork (分支) 的 dev 分支與 upstream (上游) 儲存庫同步，而不會遺失您的本地變更。

$ git merge upstream/dev

沒有衝突？測試仍然通過？變更對您來說仍然合理嗎？然後繼續並開啟一個 pull request (拉取請求)，將您的變更應用到主要 Quasar 儲存庫中的 dev 分支。

Issue (發出) pull request (拉取請求)

導航到您剛推送到的儲存庫 (例如 https://github.com/your-user-name/quasar)，然後點擊左上方面板中看到的 “New Pull Request (新的拉取請求)”。

確保您引入的變更集已包含在內。填寫一些關於您的潛在修補程式的詳細資訊，包括一個有意義的標題。完成後，按下「Create pull request (建立拉取請求)」。Quasar 核心團隊將收到關於您提交的通知。

撰寫您的故事

我們一直在尋找關於您如何使用 Quasar 或您在使用 Quasar 時的絕佳體驗的精彩文章。如果您撰寫了一篇文章，我們將在我們的 Medium 出版頻道上發布，並且我們也會確保您的文章透過我們的社群媒體曝光獲得應有的關注。如果您有興趣，請聯絡 blog(at)quasar.dev。我們很樂意收到您的來信！

建立新的 Quasar 應用程式擴展

開始為 Quasar 貢獻的一種簡單方法是將您在專案中建立的程式碼通用化，並將其發布為 Quasar 應用程式擴展。請依照本指南了解如何建立新的擴展。

完成後，在 Quasar Awesome 上提交 PR，並透過 Quasar 論壇 分享您的成就。

貢獻 Quasar UI 原始碼

與任何專案一樣，貢獻都有規則。我們的規則寫在這裡，請仔細閱讀。之後，請閱讀 Quasar 行為準則，您就可以準備好為 Quasar 的核心儲存庫做出貢獻。

一篇文章 看看原始碼 將幫助您熟悉 Quasar 程式碼庫。

Pull Request (拉取請求) 指南

• 從相關分支 checkout (切換) 出主題分支，例如 dev (Qv2) 或 v1 (Qv1)，然後 merge (合併) 回該分支。

• 請勿在 commit (提交) 中 check in (簽入) dist。

• 在您處理 PR 時，有多個小的 commit (提交) 是可以的 - 我們將讓 GitHub 在合併之前自動 squash (壓縮) 它。

• 如果新增新功能

  • 提供令人信服的理由來新增此功能。
  • 理想情況下，您應該先開啟一個建議 issue (議題) 並使其獲得批准，然後再進行處理。否則，您可能會在某些可能根本不被接受或不符合您預期的形式上花費大量時間。

• 如果修正錯誤

  • 如果您正在解決特定的 issue (議題)，請在您的 PR 標題中新增 (fix: #xxxx[,#xxx]) (#xxxx 是 issue (議題) ID)，以便更好地發布日誌，例如 fix: update entities encoding/decoding (fix #3899)。
  • 在 PR 中提供錯誤的詳細描述。最好能提供 live demo (線上示範)。

開發設定

您將需要 Node.js v16+ 版本，以及 pnpm。閱讀 package.json 並注意您可以使用的 scripts (指令稿)。

在 clone (複製) 儲存庫後，執行

$ pnpm i

常用的 NPM scripts (指令稿)

# Start dev server with a demo app. This app has Quasar source code linked directly so any change will trigger HMR (Hot Module Reload) on the dev server.
# There's a section for each feature where tests are made.
$ pnpm dev

# build all dist files, including npm packages
$ pnpm build
# build only js dist files
$ pnpm build js
# build only type related files
$ pnpm build js types
# build only css dist files
$ pnpm build css

# lint sources
$ pnpm lint

專案結構 (/ui)

• build - 包含與 build (建置) 相關的設定檔。在大多數情況下，您不需要碰觸它們。

• src - 包含原始碼。程式碼庫以 ES2015 編寫。

  • components - Quasar Vue 元件的 JS、Sass 和 JSON (API) 檔案

  • composables - 用於 Vue 3 Composition API 的 Quasar composables

  • directives - Quasar 提供的 Vue directives

  • plugins - Quasar plugins (外掛程式)

  • css - Quasar 樣式的 Sass 定義和核心程式碼

  • utils - framework (框架) 使用並匯出到 public API 的 utilities (工具程式)

• lang - Quasar 語言包

• icon-set - Quasar icon sets (圖示集)

• dist - 包含用於發布的 built (建置) 檔案 (僅在 build (建置) 後)。

• dev - 應用程式，直接連結 Quasar 原始碼，用於測試目的。每個功能/元件都有自己的 *.vue 檔案。新增一個新檔案會自動為其建立路由，並將其新增到「首頁」清單 (基於檔案名稱)。

Quasar 的 Dev Server (開發伺服器) (/ui)

執行 pnpm dev 會啟動一個 dev server (開發伺服器)，它使用 HMR (Hot Module Reload，熱模組重載) 來處理 Quasar 原始碼。您可以透過對 /dev *.vue 檔案進行必要的變更來輕鬆測試您的變更。

財務貢獻

Quasar Framework 是一個 MIT 授權的開放原始碼專案。它的持續開發歸功於這些很棒的 贊助者 的支持。

請閱讀我們的宣言，了解 為什麼捐款很重要。如果您想成為捐贈者，請查看 Quasar Framework 的捐贈活動。

Quasar 貢獻者

感謝所有已經 為 Quasar 做出貢獻的人！