跳到主要內容
版本：v8

貢獻 Ionic

感謝您對貢獻 Ionic Framework 的興趣！

貢獻禮儀​

請參閱貢獻者行為準則以了解行為規則。

建立問題​

  • 如果您對使用框架有疑問，請在 Ionic 論壇 上提問。

  • 您必須清楚描述重現您遇到的問題所必需的步驟。雖然我們很樂意盡可能幫助我們的使用者，但沒有明確的重現步驟來診斷問題非常耗時且根本無法持續。

  • Ionic 儲存庫的問題列表專用於錯誤報告和功能請求。不符合規定的問題將立即關閉。

  • 沒有明確重現步驟的問題將不會被分類。如果問題被標記為「needs: reply」，並且在 14 天以上沒有收到問題作者的任何進一步回覆，則將被關閉。

  • 如果您認為您發現了一個錯誤，或有新的功能想法，請先確保它尚未被回報。您可以搜尋現有的問題，看看是否有類似的問題被回報。包含已關閉的問題，因為它可能已透過解決方案關閉。

  • 接下來，建立一個新問題，詳細說明問題。請在提交問題之前填寫填寫好的問題表單。

建立良好的程式碼重現​

什麼是程式碼重現？​

程式碼重現是一個小型應用程式，旨在演示特定問題。程式碼重現應包含重現問題所需的最少程式碼，並應專注於單一問題。

為什麼您應該建立重現？​

您遇到的問題的程式碼重現有助於我們更好地隔離問題的原因。這是修復任何錯誤的重要第一步！

如果沒有可靠的程式碼重現，我們不太可能解決問題，導致問題被關閉。換句話說，建立問題的程式碼重現有助於我們幫助您。

如何建立重現​

  • 使用我們的其中一個入門範本建立新的 Ionic 應用程式。blank 入門應用程式是一個很棒的選擇。您可以使用以下 Ionic CLI 命令建立一個：ionic start myApp blank
  • 新增重現您遇到的問題所需的最少程式碼。不要包含任何不需要重現問題的程式碼。這包括您已安裝的任何協力廠商外掛程式。
  • 將應用程式發布到 GitHub，並在建立問題時包含其連結。
  • 請務必包含重現問題的步驟。這些步驟應該清楚且易於遵循。

建立重現的好處​

  • 使用最新版本的 Ionic：透過建立新的 Ionic 應用程式，您可以確保您正在針對最新版本的框架進行測試。有時您遇到的問題已經在較新版本的框架中解決！
  • 最小的表面積：透過刪除不需要重現問題的程式碼，可以更容易地識別問題的原因。
  • 無需秘密程式碼：建立問題的最小重現可以避免您必須發布專案中使用的任何專有程式碼。
  • 獲得修復問題的幫助：如果我們可以可靠地重現問題，我們很有可能會解決它。

建立提取請求​

  • 感謝您抽出時間貢獻！在提交提取請求之前，我們要求您先建立一個問題，說明錯誤或功能請求，並告知我們您計劃為其建立提取請求。如果問題已存在，請在該問題上留言，告知我們您想為其提交提取請求。這有助於我們追蹤提取請求，並確保沒有重複的工作。

  • 正在尋找要修復的問題？請務必查看我們標有help wanted標籤的問題！

設定​

  1. 下載安裝程式以取得 Node.js 的 LTS 版本。這也是安裝 npm 的最佳方式。
  2. Fork Ionic 儲存庫。
  3. 複製您的 Fork。
  4. 從 master 為您的變更建立一個新分支。
  5. 瀏覽至您要修改的套件 (core、angular 等) 的目錄。
  6. 執行 npm install 以安裝此套件的相依性。
  7. 請按照以下特定套件的步驟操作。

核心​

修改元件​

  1. 在 /core/src/components/ 內找到要修改的元件。
  2. 查看 Stencil 文件和其他元件，以了解這些元件的實作方式。
  3. 對元件進行變更。如果變更過於複雜或不尋常，請新增註解，以便我們了解變更。
  4. 在本機預覽您的變更。
  5. 如果需要，修改文件。
  6. 在目錄上執行 lint，並確保沒有錯誤。
  7. 建置專案.
  8. 建置完成後，提交變更。請為每個提交遵循提交訊息格式。
  9. 提交變更的提取請求。

預覽變更​

  1. 從 core 目錄內執行 npm start。
  2. 瀏覽器應該會在 https://127.0.0.1:3333/ 開啟。
  3. 從這裡，瀏覽至其中一個元件的測試以預覽您的變更。
  4. 如果測試顯示您的變更不存在，請新增一個新的測試或更新現有的測試。
  5. 若要在 RTL 模式下測試，一旦您進入所需的元件測試中，請在網址末尾加上 ?rtl=true；例如：https://127.0.0.1:3333/src/components/alert/test/basic?rtl=true。

程式碼檢查變更​

  1. 執行 npm run lint 來檢查 TypeScript 和 Sass 的程式碼。
  2. 如果出現程式碼檢查錯誤，請執行 npm run lint.fix 來自動修正任何錯誤。重複步驟 1 以確保錯誤已修正，如果沒有，則手動修正它們。
  3. 若要僅檢查和修正 TypeScript 錯誤，請分別執行 npm run lint.ts 和 npm run lint.ts.fix。
  4. 若要僅檢查和修正 Sass 錯誤，請分別執行 npm run lint.sass 和 npm run lint.sass.fix。

修改文件​

  1. 在元件的目錄中找到 readme.md 檔案。
  2. 在此檔案中，在顯示 <!-- Auto Generated Below --> 的行上方修改文件。
  3. 若要更新該行下方任何自動產生的文件，請在以下位置進行相關變更
  • Usage：更新元件 usage/ 目錄中的元件用法範例
  • Properties、Events 或 Methods：更新元件的 TypeScript 檔案 (*.tsx)
  • CSS Custom Properties：更新元件的主要 Sass 檔案 (*.scss)

修改測試​

  1. 在元件目錄的 test/ 資料夾中找到要修改的測試。
  2. 如果測試存在，請新增範例來重現已修正的問題或新增的功能，以修改測試。
  3. 如果需要新的測試，最簡單的方法是從元件的 test/ 目錄複製 basic/ 資料夾，重新命名，並編輯 index.html 和 e2e.ts 檔案中的內容（請參閱截圖測試以取得有關此檔案的更多資訊）。
  4. preview/ 資料夾在文件中用作示範。只有在測試中有錯誤或 API 有未在測試中更新的變更時，才更新此測試。
截圖測試​
  1. 如果測試存在於截圖中，則在測試目錄中會有一個名為 e2e.ts 的檔案。
  2. 可以透過包含此檔案並新增一個或多個包含呼叫 page.compareScreenshot() 的 test() 呼叫來新增截圖測試。請參閱Stencil 端對端測試和 core/ 中的現有測試範例。
  3. 重要：每個 test() 應只有一個截圖 (page.compareScreenshot()) 呼叫或應在每個測試結束時檢查 expect。如果存在不符的情況，它會使測試失敗，這將阻止其餘的測試執行，即如果第一個截圖失敗，則其餘的截圖呼叫將不會被呼叫，除非它們位於單獨的測試中或所有 expect 都在結尾呼叫。
  4. 若要在本機執行截圖，請使用以下命令：npm run test.screenshot。
    • 若要針對特定測試執行截圖，請傳遞測試的路徑或要搜尋的字串。
    • 例如，執行所有 alert 測試：npm run test.screenshot alert。
    • 或者，執行基本的 alert 測試：npm run test.screenshot src/components/alert/test/basic/e2e.ts。

建置變更​

  1. 完成所有變更並更新文件後，請在 core 目錄內執行 npm run build。如有必要，這會將您的變更新增至任何自動產生的檔案。
  2. 檢閱變更，如果一切看起來正確，請提交變更。
  3. 請務必在提交之前完成建置。如果您對文件、屬性、方法或任何其他需要更新產生檔案的內容進行了變更，則需要提交此變更。
  4. 推送變更後，發布分支並建立提取請求。

提交提取請求​

  1. 建立新的提取請求，以 master 分支作為 base。您可能需要按一下 compare across forks 來尋找您的變更。
  2. 請參閱從分支建立提取請求 GitHub 說明文章，以取得更多資訊。
  3. 請盡您所能填寫提供的提取請求範本，並包含任何相關的問題。

提交訊息準則​

我們對於 Git 提交訊息的格式有非常精確的規則。這會產生易於閱讀的訊息，在瀏覽專案歷程記錄時易於遵循。我們也使用 Git 提交訊息來產生我們的變更記錄。我們的格式與 Angular 的提交訊息準則非常相似。

提交訊息格式​

我們遵循傳統提交規範。提交訊息由標頭、本文和頁尾組成。標頭具有類型、範圍和主旨

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

標頭是必要的，而標頭的範圍是選用的。

還原​

如果提交還原先前的提交，則應以 revert: 開頭，後接還原提交的標頭。在本文中應說明：This reverts commit <hash>.，其中 hash 是被還原提交的 SHA。

類型​

如果前置詞是 feat、fix 或 perf，它將會出現在變更記錄中。但是，如果有任何重大變更，提交將始終出現在變更記錄中。

必須是以下其中之一

  • feat：新功能
  • fix：錯誤修正
  • docs：僅限文件變更
  • style：不影響程式碼意義的變更（空白、格式、缺少分號等）
  • refactor：既不修正錯誤也不新增功能的程式碼變更
  • perf：可提升效能的程式碼變更
  • test：新增遺失的測試
  • chore：對建置程序或輔助工具和程式庫（例如文件產生）的變更

範圍​

範圍可以是指定提交變更位置的任何內容。通常它會參考元件，但也可能參考公用程式。例如 action-sheet、button、css、menu、nav 等。如果您為同一個元件進行多次提交，請保持此元件的命名一致。例如，如果您對導覽進行變更，並且第一次提交是 fix(nav)，則您應繼續使用 nav 進行任何與導覽相關的提交。一般而言，如果您正在修改元件，請使用資料夾的名稱。

主旨​

主旨包含對變更的簡潔描述

  • 使用祈使語氣的現在式：「change」而不是「changed」或「changes」
  • 請勿將第一個字母大寫
  • 請勿在末尾加上句點 .
  • 提交訊息的總長度不得超過 50 個字元
  • 描述提交的作用，而不是它與哪個問題相關或修正了哪個問題
  • 簡潔但具描述性 - 我們應該透過閱讀主旨來充分了解提交的作用

本文​

如同在主旨中一樣，使用祈使語氣的現在式：「change」而不是「changed」或「changes」。本文應包含變更的動機，並將此與先前的行為進行對比。

頁尾應包含有關重大變更的任何資訊，並且也是參考此提交關閉的 GitHub 問題的位置。

重大變更應以 BREAKING CHANGE: 這個字詞開頭，後接一個空格或兩個換行符號。然後將提交訊息的其餘部分用於此目的。

範例​

不會出現在產生的變更記錄中

docs(changelog): update steps to update

出現在「功能」標題和 toast 子標題下

feat(toast): add 'buttons' property

出現在「錯誤修正」標題和 skeleton-text 子標題下，並連結至問題 #28

fix(skeleton-text): use proper color when animated

closes #28

出現在「效能改進」標題下，以及「重大變更」標題下，並附帶重大變更說明

perf(css): remove all css utility attributes

BREAKING CHANGE: The CSS utility attributes have been removed. Use CSS classes instead.

出現在「重大變更」標題下，並附帶重大變更說明

refactor(animations): update to new animation system

BREAKING CHANGE:

Removes the old animation system to use the new Ionic animations.

如果下列提交和提交 667ecc1 位於同一個版本下，則不會出現在變更記錄中。如果不是，還原提交會出現在「還原」標題下。

revert: feat(skeleton-text): add animated property

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

授權條款​

透過將您的程式碼貢獻給 ionic-team/ionic GitHub 儲存庫，您同意根據 MIT 授權條款授權您的貢獻。

目錄

編輯此頁面