跳到主內容

如何參與開發

感謝您對為 CubeCOS 貢獻心力感興趣。為了打造一個供社區使用的開放空間，請您仔細閱讀並遵循本文件中的指引。

行為準則​

我們致力於營造一個正向的社群環境，並以我們的《行為準則》（./code-of-conduct ）為指引。

您可以透過 [email protected] 與我們聯繫

先決條件​

建立 GitHub 帳戶​

若您尚未擁有 GitHub 帳戶，請先建立一個。

設定 Git 提交簽名​

Git 提交簽名是一種利用加密簽名（GPG 或 SSH 金鑰）來驗證提交作者真實性的流程，藉此確保該提交是由可信賴的身分所建立，且未遭篡改。為確保安全性並驗證開發者來源憑證的簽署，我們要求貢獻者在提交時簽名。設定 Git 提交簽名

如何參與開發​

我們歡迎以下形式的貢獻：

  • 新功能
  • 錯誤修正或功能增強
  • 問題分類
  • 文件
  • 在 Slack 或 Discord 上回答問題
  • 傳播／社群媒體／部落格文章

請勿在問題追蹤系統或 PR 中回報任何 安全性 問題。請遵循我們的 安全 政策，了解如何回報問題及聯絡我們。

簽署你的貢獻​

我們採用 開發者來源憑證 v1.1，以確保貢獻已獲得適當授權，並符合開源標準。

Git 提交簽署（commit sign-off）是您聲明遵守《開發者來源證明》（DCO）的一種方式，透過在提交訊息中加入 Signed-off-by: 這一行，以確認您是該變更的作者，或已獲得貢獻該變更的授權。

請在提交訊息中加入以下內容以完成簽核。您的簽名必須與該提交所關聯的 Git 使用者及電子郵件地址相符。

This is my commit message

Signed-off-by: Your Name <[email protected]>

在 Git 中，透過 --signoff (-s) 選項，DCO 會自動完成，方法如下

git commit -s -m "Description of the commit"

開發​

開發環境是在容器化實例中執行 CubeCOS，這需要大量的記憶體資源才能可靠地運作。以下規格僅適用於開發環境的軟體與硬體需求。

有關生產環境部署及 CubeCOS 的完整設定詳情，請參閱 CubeCOS 文件中的 安裝 章節。

硬體需求​

  • CPU
    • 架構：x86_64
    • 8C/16T 核心，2.0 GHz 或更高
    • 硬體虛擬化支援（支援 Intel VT-x／AMD-V）
  • 記憶
    • 最低需求：64 GiB
  • 硬碟
    • 最低要求：500 GiB 可用空間

軟體需求​

  • 主機作業系統
    • CentOS 8
    • CentOS Stream 8
    • CentOS Stream 9
  • Git
  • Git LFS
  • Docker (docker-ce)

下載程式碼​

使用遞迴旗標複製儲存庫，以包含所有子模組。

git clone --recursive [email protected]:bigstack-oss/cubecos.git

建置產物​

  1. 建立並進入開發空間

    預設專案名稱是 centos9-jail，建置過程會在 CubeCOS 儲存庫的同一路徑下，建立一個以該預設專案名稱命名的全新資料夾。

    若要以預設專案名稱進行建置並進入建置完成的容器，請執行以下指令：

    cd cubecos
    make centos9-jail enter

    若要使用自訂專案名稱進行建置（這對於多個部署流程或測試情境相當實用）：

    cd cubecos
    make PROJECT=your-project-name centos9-jail enter

    若未指定 PROJECT 名稱，建置程序將預設使用 centos9-jail，並以此名稱建立建置目錄與容器。

    建立完開發空間後，您會在目錄下看到兩個資料夾：

    • cubecos/ – 主要原始碼儲存庫
    • centos9-jail/（或您自訂的專案名稱）隔離的開發環境
    build-bench > ls ..
    cubecos centos9-jail

    執行 make PROJECT=example centos9-jail 將建立一個名為 example 的新建置開發空間。對應的建置資料夾同樣會命名為 example，並會建立在 cubecos 資料夾的主目錄中。

    執行 make PROJECT=example centos9-jail 會建立另一個名為 example 的開發空間，而建置資料夾將位於 cubecos 資料夾的父目錄下，並命名為 example

    cubecos> ls ..
    cubecos centos9-jail example

    我們可以使用 make enter 指令進入預設的建置開發空間 centos9-jail。或者，執行 make PROJECT=example enter 即可進入名為 example 的建置隔離區。

  2. 透過指定建置參數，來建置各種 CubeCOS 安裝媒體。

    建置指令僅能在 CubeCOS 建置隔離環境中執行。在嘗試建立 CubeCOS 安裝媒體之前，請先建立並進入一個開發空間，或進入現有的開發空間。 「build」指令可產生以下類型的安裝媒體：

    1. full：建立所有受支援的 CubeCOS 安裝媒體（ISO、USB、PXE 及套件檔案）。
    2. pxe：產生用於透過 PXE 伺服器進行系統部署的網路開機檔案。
    3. pxeserver：建立完整的 PXE 伺服器映像檔，用於託管網路開機檔案。
    4. pxeserveriso：建立 PXE 伺服器映像檔的 ISO 版本。
    5. usb：建立用於透過 USB 隨身碟進行實體安裝的 USB 可開機映像檔。
    6. iso：產生一個 ISO 映像檔，用作虛擬媒體。
    7. liveusb：建立一個可直接執行 CubeCOS 且無需安裝的 Live USB 映像檔。
    # all installation types
    [root@centos9-jail centos9-jail]# make full

    # network boot
    [root@centos9-jail centos9-jail]# make pxe

    # usb media
    [root@centos9-jail centos9-jail]# make usb

    # iso generation
    [root@centos9-jail centos9-jail]# make iso

  3. 尋找輸出的媒體

    建置產出檔案可能位於建置資料夾內的 core/main/ship 目錄下。

    • CUBE_XXX.img：USB 安裝程式
      • 使用 dd bs=4M if=<img_file_path> of=<usb_device_name> status=progress oflag=sync 將其寫入 USB 隨身碟
      • 使用 USB 隨身碟啟動伺服器
      • 請依照 登入並還原以設定 CubeCOS 的步驟，對系統分割區進行韌體更新。
    • CUBE_XXX.iso：CubeCOS ISO
    • CUBE_XXX.pkg：CubeCOS 檔案系統存檔
    • CUBE_XXX.pxe.tgz：此壓縮檔包含用於設定 PXE 伺服器，以便透過 PXE 安裝 CubeCOS 的組件

    此外，core/main/ship 目錄下的每個建構產出皆附有 MD5 雜湊值。

  4. 清理建置的開發環境

    make distclean

備註

在重新進入開發空間時，或是在任何需要清理建置殘餘檔案的情況下，建議使用 make distclean 來清理先前建置產生的殘餘檔案。

系統排錯​

除了 git-lfs 之外，請確保 hex（git 子模組）已正確抄寫至您的頂層原始碼目錄下。

ls -lt cubecos/hex