貢獻

Nuxt 是一個社群專案 - 我們歡迎各種形式的貢獻！❤️

您可以透過多種不同的方式為 Nuxt 生態系統做出貢獻。

生態系統

Nuxt 生態系統包括許多不同的專案和組織。

  • nuxt/- Nuxt 框架本身的核心儲存庫。nuxt/nuxt包含 Nuxt 框架（版本 2 和 3）。
  • nuxt-modules/- 社群貢獻和維護的模組和庫。將模組遷移到 nuxt-modules 有一個過程。雖然這些模組有獨立的維護者，但它們不依賴於某一個人。
  • unjs/- 許多這些庫在整個 Nuxt 生態系統中使用。它們被設計成與框架和環境無關的通用庫。我們歡迎其他框架和專案貢獻和使用。

如何貢獻

分類問題並在討論中提供幫助

檢視您想要幫助的專案的議題和討論。例如，這裡是Nuxt 的議題面板。等等討論幫助其他使用者、分享解決方案、建立復現或甚至深入研究一個小錯誤並分享您的發現都會產生巨大的影響。

建立議題

感謝您花時間建立議題！❤️

  • 報告 bug：請檢視我們的指南，瞭解在提出議題之前需要做的一些事情。
  • 功能請求：檢查是否已有涵蓋您想法中功能的現有議題或討論。如果該功能屬於 Nuxt 生態系統的其他部分（例如模組），請考慮首先在該處提出功能請求。如果您想法中的功能是通用的或者 API 尚不完全清楚，請考慮在“想法”部分開啟討論，以便首先與社群討論。

我們將盡力遵循內部議題決策流程圖來回複議題。

傳送拉取請求

我們始終歡迎拉取請求！❤️

開始之前

在修復 bug 之前，我們建議您檢查是否存在描述該 bug 的議題，因為這可能是文件問題，或者可能有一些有用的上下文資訊。

如果您正在開發一個功能，我們要求您首先提出功能請求議題，以便與維護者討論該功能是否需要——以及這些功能的設計。這有助於節省維護者和貢獻者的時間，並意味著功能可以更快地釋出。該議題應該由框架團隊成員確認後，才能在拉取請求中構建該功能。

對於拼寫錯誤修復，建議將多個拼寫錯誤修復批次提交到一個拉取請求中，以保持更清晰的提交歷史。

對於 Nuxt 本身較大的更改，我們建議您首先建立一個 Nuxt 模組並在其中實現該功能。這有助於快速進行概念驗證。然後您可以以討論的形式建立一個 RFC。隨著使用者採納並收集反饋，它就可以進行完善並新增到 Nuxt 核心，或者繼續作為一個獨立的模組。

提交約定

我們使用Conventional Commits用於提交訊息，這允許自動生成變更日誌根據提交。如果您還不熟悉，請通讀本指南。

請注意，fix: 和 feat: 用於實際程式碼更改（可能影響邏輯）。對於拼寫錯誤或文件更改，請改用 docs: 或 chore:。

  • fix: typo -> docs: fix typo

如果您在 monorepo 專案中工作，例如 nuxt/nuxt，請確保在括號中指定提交的主要範圍。例如：feat(kit): add 'addMagicStuff' utility。

建立拉取請求

如果您不知道如何傳送拉取請求，我們建議您閱讀該指南.

傳送拉取請求時，請確保您的 PR 標題也遵循提交約定。

如果您的 PR 修復或解決了現有議題，請務必在 PR 描述中提及它們。

單個 PR 中可以有多個提交；您無需為您的更改進行 rebase 或強制 push，因為我們將在合併時使用 Squash and Merge 將提交壓縮成一個提交。

我們沒有新增任何提交鉤子以允許快速提交。但在您提出拉取請求之前，您應該確保所有 lint/測試指令碼都透過。

通常，也請確保 PR 中沒有**不相關**的更改。例如，如果您的編輯器對您編輯的檔案中其他位置的空白或格式進行了任何更改，請撤銷這些更改，以便更清楚地顯示您的 PR 更改了什麼。並且請避免在一個 PR 中包含多個不相關的功能或修復。如果可以分離它們，最好有多個 PR 分別進行審查和合並。通常，一個 PR 應該只做**一件事**。

您提交拉取請求後

您提交拉取請求後，我們將盡力及時進行審查。

如果我們將其分配給維護者，則意味著該維護者將特別注意審查並實施可能需要的任何更改。

如果我們要求對 PR 進行更改，請忽略紅色文字！這並不意味著我們認為這是一個糟糕的 PR——這只是一種可以一目瞭然地輕鬆瞭解拉取請求列表狀態的方法。

如果我們將 PR 標記為“待處理”，則表示我們在審查 PR 時可能還有其他任務要做——這是一個內部便箋，不一定反映 PR 是一個好主意與否。我們將盡力透過評論解釋待處理狀態的原因。

我們將盡力遵循我們的 PR 決策流程圖來響應和審查拉取請求。

AI 輔助貢獻

我們歡迎在貢獻 Nuxt 時審慎使用 AI 工具，但要求所有貢獻者遵循兩個核心原則.

絕不允許大型語言模型 (LLM) 代您發言

  • 所有評論、議題和拉取請求描述都應以您自己的口吻撰寫
  • 我們重視清晰的人際交流，而不是完美的語法或拼寫
  • 避免複製貼上不反映您自己理解的 AI 生成摘要

絕不允許大型語言模型 (LLM) 代您思考

  • 隨意使用 AI 工具生成程式碼或探索想法
  • 只提交您完全理解並能解釋的貢獻
  • 貢獻應反映您自己的推理和解決問題的能力

我們的目標是確保質量並保持與真實人員協作和交流的樂趣。如果您對改進 Nuxt 社群的 AI 政策有任何想法，我們非常樂意傾聽！❤️

建立模組

如果您使用 Nuxt 構建了一些很酷的東西，為什麼不將其提取為模組，以便與他人共享呢？我們已經有許多優秀的模組，但總有更多的空間。

如果您在構建時需要幫助，請隨時聯絡我們。

發起 RFC

我們強烈建議您先建立一個模組，以測試新的大型功能並獲得社群的採納。

如果您已經這樣做了，或者不適合建立新模組，那麼請首先建立一個新的討論。確保儘可能清晰地解釋您的想法。包括新 API 的程式碼示例或函式簽名。引用現有問題或痛點並提供示例。

如果我們認為這應該是一個 RFC，我們將更改類別為 RFC 並更廣泛地進行傳播以徵求反饋。

一個 RFC 將經歷以下階段

  • rfc: active - 當前開放評論
  • rfc: approved - 經 Nuxt 團隊批准
  • rfc: ready to implement - 已建立並分配實現問題的議題
  • rfc: shipped - 已實現
  • rfc: archived - 未批准，但已歸檔以供將來參考

生態系統內的約定

以下約定在 nuxt/ 組織內是**必需的**，並推薦給生態系統中的其他維護者。

模組約定

模組應遵循Nuxt 模組模板。有關更多資訊，請參閱模組指南。

使用核心 unjs/ 庫

我們推薦以下在整個生態系統中使用到的庫

  • pathe- 通用路徑工具（取代 Node 的 path）
  • ufo- URL 解析和連線工具
  • unbuild- 基於 Rollup 的構建系統
  • ... 更多請檢視unjs/組織！

使用 ESM 語法並預設 type: module

大多數 Nuxt 生態系統可以直接使用 ESM。通常，我們主張您避免使用 CJS 特有的程式碼，例如 __dirname 和 require 語句。您可以閱讀更多關於 ESM 的資訊。

什麼是 Corepack

Corepack確保您在執行相應命令時使用正確版本的包管理器。專案可能在其 package.json 中包含 packageManager 欄位。

在如下配置的專案下，Corepack 將安裝 pnpm 的 v7.5.0 版本（如果您尚未安裝）並使用它來執行您的命令。

package.json
{
  "packageManager": "[email protected]"
}

使用 ESLint

我們使用ESLint進行 linting 和格式化，並使用@nuxt/eslint.

IDE 設定

我們建議使用VS Code以及ESLint 擴充套件。如果您願意，可以在儲存正在編輯的程式碼時啟用自動修復和格式化

settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll": "never",
    "source.fixAll.eslint": "explicit"
  }
}

不使用 Prettier

由於 ESLint 已經配置為格式化程式碼，因此無需使用 Prettier 重複此功能。要格式化程式碼，您可以執行 yarn lint --fix、pnpm lint --fix 或 bun run lint --fix，或參考ESLint 部分進行 IDE 設定。

如果您的編輯器中安裝了 Prettier，我們建議您在專案工作時停用它，以避免衝突。

包管理器

我們推薦使用 pnpm 作為模組、庫和應用程式的包管理器。

啟用 Corepack 很重要，以確保您使用的包管理器版本與專案一致。Corepack 內置於新的 Node 版本中，可實現無縫的包管理器整合。

要啟用它，請執行

終端
corepack enable

您只需在計算機上安裝 Node.js 後執行此操作一次。

文件風格指南

文件是 Nuxt 不可或缺的一部分。我們致力於成為一個直觀的框架——其中很大一部分是確保整個生態系統的開發者體驗和文件都完美無缺。👌

這裡有一些可能有助於改進文件的提示

  • 儘可能避免使用“簡單地”、“僅僅”、“顯然”等主觀詞語。
    請記住您的讀者可能具有不同的背景和經驗。因此，這些詞語並不能傳達明確的含義，甚至可能造成傷害。
    只需確保函式返回一個 promise。
    確保函式返回一個Promise.
  • 優先使用主動語態.
    Nuxt 將丟擲錯誤。
    Nuxt 將丟擲一個錯誤。
瞭解如何為文件做出貢獻。