refactor: Incorporate 3.0.2 version of the subject template(CI/CD imp…

…lementation)

Signed-off-by: 林博仁(Buo-ren Lin) <[email protected]>

.editorconfig

@@ -20,7 +20,7 @@ insert_final_newline = true
 trim_trailing_whitespace = true
 
 # Git configuration files uses tabs as indentation units
-[.git*]
+[/.git{modules,config}]
 indent_style = tab
 
 # Avoid git patch fail to apply due to stripped unmodified lines that contains only spaces
@@ -59,3 +59,8 @@ indent_size = 2
 
 [.*.{yml,yaml}]
 indent_size = 2
+
+# Keep the indentation style of the license text verbatim
+[/LICENSES/*]
+indent_size = unset
+indent_style = unset

.gitattributes

@@ -12,7 +12,13 @@
 
 # Avoid exporting development files to release archive
 /.* export-ignore
-/continuous-integration/ export-ignore
+/continuous-integration export-ignore
 
 # Keep editorconfig for ease of editing of product files
 /.editorconfig -export-ignore
+
+# Keep REUSE DEP5 declaration file in the release archive for legal
+# conformance
+/.reuse/ -export-ignore
+/.reuse/* export-ignore
+/.reuse/dep5 -export-ignore

.github/workflows/check-potential-problems.yml

@@ -9,14 +9,17 @@
 # SPDX-License-Identifier: CC-BY-SA-4.0
 name: 檢查專案中的潛在問題
 on:
-  - push
+  push:
+    branches:
+      - '**'
 jobs:
   check-using-precommit:
     name: 使用 pre-commit 檢查專案中的潛在問題
     runs-on: ubuntu-22.04
     env:
       PIP_CACHE_DIR: ${{ github.workspace }}/.cache/pip
       PRE_COMMIT_HOME: ${{ github.workspace }}/.cache/pre-commit
+      SHELLCHECK_DIR: ${{ github.workspace }}/.cache/shellcheck-stable
     steps:
       - name: 自版控庫取出內容
         uses: actions/checkout@v4
@@ -34,7 +37,19 @@ jobs:
           key: pre-commit|${{ env.PY }}|${{ hashFiles('.pre-commit-config.yaml') }}
           path: ${{ env.PRE_COMMIT_HOME }}
 
-      - name: Running static analysis program
+      - name: >-
+          Configure pre-built ShellCheck cache to speed up continuous integration
+        uses: actions/cache@v3
+        with:
+          key: ${{ runner.os }}-${{ runner.arch }}-shellcheck
+          path: ${{ env.SHELLCHECK_DIR }}
+
+      - name: >-
+          Patch the sudo security policy so that programs run via sudo
+          will recognize environment variables predefined by GitHub
+        run: sudo ./continuous-integration/patch-github-actions-sudo-security-policy.sh
+
+      - name: Run the static analysis programs
         run: |
           sudo ./continuous-integration/do-static-analysis.install-system-deps.sh
           ./continuous-integration/do-static-analysis.sh

.github/workflows/release.yml

@@ -18,8 +18,27 @@ jobs:
     name: Release product and their build aritfacts
     runs-on: ubuntu-20.04
     steps:
-      - name: Checkout content from the Git repository
+      - name: Check out content from the Git repository
         uses: actions/checkout@v4
+        with:
+          # Increase fetch depth if you may have more than this amount
+          # of revisions between releases
+          fetch-depth: 100
+
+          # Fetch tags as well to generate detailed changes between two releases
+          # WORKAROUND: Adding this option triggers actions/checkout#1467
+          #fetch-tags: true
+
+      - name: >-
+          WORKAROUND: Fetch tags that points to the revisions
+          checked-out(actions/checkout#1467)
+        run: |-
+          git fetch \
+            --prune \
+            --prune-tags \
+            --force \
+            --depth=100 \
+            --no-recurse-submodules
 
       - name: Determine the project identifier
         run: printf "project_id=${GITHUB_REPOSITORY##*/}\\n" >> $GITHUB_ENV
@@ -33,6 +52,11 @@ jobs:
       - name: Determine the release identifier
         run: printf "release_id=${project_id}-${release_version}\\n" >> $GITHUB_ENV
 
+      - name: >-
+          Patch the sudo security policy so that programs run via sudo
+          will recognize environment variables predefined by GitHub
+        run: sudo ./continuous-integration/patch-github-actions-sudo-security-policy.sh
+
       - name: Generate the release archive
         run: |-
           sudo ./continuous-integration/generate-build-artifacts.install-system-deps.sh

.gitignore

@@ -86,5 +86,5 @@
 # Don't track GNU gettext machine-readable message catalogs
 *.mo
 
-# Don't track continuous intregration virtual environments
+# Don't track continuous integration virtual environments
 /continuous-integration/venv/

.gitlab-ci.yml

@@ -16,12 +16,14 @@ do-static-analysis:
   variables:
     PIP_CACHE_DIR: ${CI_PROJECT_DIR}/.cache/pip
     PRE_COMMIT_HOME: ${CI_PROJECT_DIR}/.cache/pre-commit
+    SHELLCHECK_DIR: ${CI_PROJECT_DIR}/.cache/shellcheck-stable
   cache:
     # Enable per-job and per-branch caching
     key: $CI_JOB_NAME-$CI_COMMIT_REF_SLUG
     paths:
       - ${PIP_CACHE_DIR}
       - ${PRE_COMMIT_HOME}
+      - ${SHELLCHECK_DIR}
 
   script:
     - ./continuous-integration/do-static-analysis.install-system-deps.sh

.gitmodules

@@ -5,7 +5,7 @@
 # * Git - gitmodules Documentation
 #   https://git-scm.com/docs/gitmodules
 #
-# Copyright 2021 林博仁(Buo-ren, Lin) <Buo.Ren.Lin@gmail.com>
+# Copyright 2024 林博仁(Buo-ren Lin) <buo.ren.lin@gmail.com>
 # SPDX-License-Identifier: CC-BY-SA-4.0
 [submodule "Docker"]
 	path = Docker

.pre-commit-config.yaml

@@ -42,13 +42,34 @@ repos:
   # Check REUSE compliance
   # https://reuse.software/
   - repo: https://github.com/fsfe/reuse-tool
-    rev: v1.0.0
+    rev: v4.0.3
     hooks:
       - id: reuse
 
+  # Check shell scripts with ShellCheck
+  # NOTE: ShellCheck must be available in the command search PATHs
+  # https://www.shellcheck.net/
+  # https://github.com/jumanjihouse/pre-commit-hooks#shellcheck
+  - repo: https://github.com/jumanjihouse/pre-commit-hooks
+    rev: 3.0.0
+    hooks:
+      - id: shellcheck
+
   # Check YAML files
   # https://github.com/adrienverge/yamllint
   - repo: https://github.com/adrienverge/yamllint
     rev: v1.30.0
     hooks:
       - id: yamllint
+
+  # Check EditorConfig style compliance
+  # https://github.com/editorconfig-checker/editorconfig-checker.python
+  - repo: https://github.com/editorconfig-checker/editorconfig-checker.python
+    rev: 2.7.3
+    hooks:
+      - id: editorconfig-checker
+        alias: ec
+        exclude: |
+          (?ix)^(
+            LICENSES/.*
+          )$

README.md

@@ -1,12 +1,14 @@
-# 虛擬化 Virtualization
+# 虛擬化<br>Virtualization
 
 將一個或多個實體資源，如硬體、作業系統、應用程式或資料儲存，透過軟體技術的手段，將其抽象化、隔離化、統合化及自動化，形成一個或多個虛擬的資源，讓使用者可以彈性地使用和管理這些虛擬化的資源，並且可以在不影響其他虛擬化資源的情況下進行管理和配置
 
 <https://gitlab.com/libre-knowledge/virtualization>  
-[![GitLab CI 持續整合流程狀態標章](https://gitlab.com/libre-knowledge/virtualization/badges/main/pipeline.svg?ignore_skipped=true "點擊查看 GitLab CI 持續整合流程的運行狀態")](https://gitlab.com/libre-knowledge/virtualization/-/commits/main) [![「檢查專案中的潛在問題」GitHub Actions 作業流程狀態標章](https://github.com/libre-knowledge/virtualization/actions/workflows/check-potential-problems.yml/badge.svg "本專案使用 GitHub Actions 自動化檢查專案中的潛在問題")](https://github.com/libre-knowledge/virtualization/actions/workflows/check-potential-problems.yml) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white "本專案使用 pre-commit 檢查專案中的潛在問題")](https://github.com/pre-commit/pre-commit) [![REUSE 規範遵從狀態標章](https://api.reuse.software/badge/github.com/libre-knowledge/virtualization "本專案遵從 REUSE 規範降低軟體授權合規成本")](https://api.reuse.software/info/github.com/libre-knowledge/virtualization)
+[![GitLab CI 持續整合流程狀態標章](https://gitlab.com/libre-knowledge/virtualization/badges/main/pipeline.svg?ignore_skipped=true "點擊查看 GitLab CI 持續整合流程的運行狀態")](https://gitlab.com/libre-knowledge/virtualization/-/commits/main) [![「檢查專案中的潛在問題」GitHub Actions 作業流程狀態標章](https://github.com/libre-knowledge/virtualization/actions/workflows/check-potential-problems.yml/badge.svg "本專案使用 GitHub Actions 自動化檢查專案中的潛在問題")](https://github.com/libre-knowledge/virtualization/actions/workflows/check-potential-problems.yml) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white "本專案使用 pre-commit 檢查專案中的潛在問題")](https://github.com/pre-commit/pre-commit) [![REUSE 規範遵從狀態標章](https://api.reuse.software/badge/gitlab.com/libre-knowledge/virtualization "本專案遵從 REUSE 規範降低軟體授權合規成本")](https://api.reuse.software/info/gitlab.com/libre-knowledge/virtualization)
 
 ## 基本概念
 
+以下列舉本主題相關的基本概念說明資源：
+
 ### 主端<br>Host
 
 運行虛擬化解決方案的主機，負責提供運算資源給[客端](#客端-guest)使用，一個虛擬化主端系統可以運行多個[客端](#客端-guest)環境
@@ -15,17 +17,17 @@
 
 於[主端](#主端-host)上運行的虛擬運算環境，與主端系統有一定程度的隔離，可以存取的資源受限
 
-### 虛擬化監管器<br>Hypervisor / Virtual Machine Monitor(VMM)
+### 虛擬機監管器<br>Virtual Machine Hypervisor / Virtual Machine Monitor(VMM)
 
 於[主端](#主端-host)運算環境運行，管理並分配硬體資源給[客端](#客端-guest)的系統或應用
 
-### 原生/裸機型虛擬化監管器（第一類虛擬化監管器）<br>Native/Bare-metal hypervisor(TYPE-1 Hypervisor)
+### 原生/裸機型虛擬機監管器（第一類虛擬機監管器）<br>Native/Bare-metal hypervisor(TYPE-1 Hypervisor)
 
-直接運行於主機硬體上（而非一般用途作業系統上）的虛擬化監管器，運行效能相對第二類虛擬化監管器較好
+直接運行於主機硬體上（而非一般用途作業系統上）的虛擬機監管器，運行效能相對第二類虛擬機監管器較好
 
-### 託管型虛擬化監管器（第二類虛擬化監管器）<br>Hosted hypervisor(TYPE-2 Hypervisor)
+### 託管型虛擬機監管器（第二類虛擬機監管器）<br>Hosted hypervisor(TYPE-2 Hypervisor)
 
-以應用軟體的方式運行於一般用途作業系統上的[虛擬化監管器](#虛擬化監管器-hypervisor-virtual-machine-monitor-vmm)，運行效能較第一類虛擬化監管器差
+以應用軟體的方式運行於一般用途作業系統上的[虛擬機監管器](#虛擬機監管器-virtual-machine-hypervisor-virtual-machine-monitor-vmm)，運行效能較第一類虛擬機監管器差
 
 ### 硬體虛擬化<br>Hardware virtualization
 
@@ -37,75 +39,66 @@
 
 由於必須要翻譯所有的客端請求為主端指令故效能較差
 
-相關的解決方案：
-
-* QEMU（未使用等[伴虛擬化](#伴虛擬化-para-virtualization)支援的情況下）
-* Oracle VirtualBox（6.1 版之前非 64位元與多執行緒的客體系統虛擬化）
-
-### 伴虛擬化<rp>(</rp><rt>Para-virtualization</rt><rp>)
+### 伴虛擬化<br>Para-virtualization
 
 透過與[客端](#客端-guest)作業系統特別提供的界面交互來減少需要大量運算或時間才能處理的[客端](#客端-guest)操作，藉以改善虛擬化效能的技術
 
-需要[主端](#主端-host)[虛擬化監管器](#虛擬化監管器-hypervisor-virtual-machine-monitor-vmm)與[客端](#客端-guest)作業系統支援對應的 API 才能夠使用（如 Linux）
-
-相關方案：
-
-* VMware ESXi
-* Hyper-V
-* QEMU（搭配 KVM）
-* Xen
+需要[主端](#主端-host)[虛擬機監管器](#虛擬機監管器-virtual-machine-hypervisor-virtual-machine-monitor-vmm)與[客端](#客端-guest)作業系統支援對應的 API 才能夠使用（如 Linux）
 
 ### 硬體輔助虛擬化<br>Hardware-assisted virtualization
 
 由中央處理器、晶片組等硬體提供，將虛擬機器的部份工作取代以提高虛擬機器運行效能的虛擬化解決方案
 
-須硬體、韌體與[虛擬化監管器](#虛擬化監管器-hypervisor-virtual-machine-monitor-vmm)支援
+須硬體、韌體與[虛擬機監管器](#虛擬機監管器-virtual-machine-hypervisor-virtual-machine-monitor-vmm)支援
 
-相關硬體解決方案：
+### 作業系統層級虛擬化<br>Operating system level virtualization
 
-* VT-x/AMD-V
-* VT-d
-* VT-c
-* AMD-Si
-* Extended Page Tables(Second Level Address Translation (SLAT))
+透過抽象化作業系統的功能與命名空間等隔離技術使多個客端作業系統可以與主端作業系統共用作業系統核心並同行運行的技術
 
-相關虛擬化監管器解決方案：
+## 解決方案
 
-* KVM
-* QEMU（搭配 KVM）
-* XEN（搭配 KVM）
-* Oracle VirtualBox
+以下列舉本主題相關的解決方案：
 
-### 作業系統層級虛擬化<br>Operating system level virtualization
+### 虛擬機監管器
 
-透過抽象化作業系統的功能與命名空間等隔離技術使多個客端作業系統可以與主端作業系統共用作業系統核心並同行運行的技術
+* ESXi  
+  由 VMware 推出之支援[伴虛擬化](#伴虛擬化-para-virtualization)的[原生/裸機型虛擬機監管器](#原生裸機型虛擬機監管器第一類虛擬機監管器nativebare-metal-hypervisortype-1-hypervisor)解決方案
+* Hyper-V  
+  由微軟所推出之支援[伴虛擬化](#伴虛擬化-para-virtualization)的[原生/裸機型虛擬機監管器](#原生裸機型虛擬機監管器第一類虛擬機監管器nativebare-metal-hypervisortype-1-hypervisor)解決方案
+* QEMU  
+  支援[全虛擬化](#全虛擬化-full-virtualization)與（搭配 KVM）[伴虛擬化](#伴虛擬化-para-virtualization)的[託管型虛擬機監管器](#託管型虛擬機監管器第二類虛擬機監管器hosted-hypervisortype-2-hypervisor)解決方案
+* VirtualBox  
+  由<ruby>甲骨文<rp>(</rp><rt>Oracle</rt><rp>)</rp></ruby>公司推出之具備使用者友善的圖形化操作界面、支援[伴虛擬化](#伴虛擬化-para-virtualization)的[託管型虛擬機監管器](#託管型虛擬機監管器第二類虛擬機監管器hosted-hypervisortype-2-hypervisor)解決方案
+* Xen  
+  支援[全虛擬化](#全虛擬化-full-virtualization)與（搭配 KVM）[伴虛擬化](#伴虛擬化-para-virtualization)的開放來源碼[原生/裸機型虛擬機監管器](#原生裸機型虛擬機監管器第一類虛擬機監管器nativebare-metal-hypervisortype-1-hypervisor)解決方案
 
-相關方案：
+### 作業系統層級虛擬化
 
-* Docker
+* [Docker](https://gitlab.com/libre-knowledge/docker)  
+  主流的容器實現之一
 * Kubernetes
 * Podman
 * LXC
 * LXD
 
-## 解決方案
+### 硬體輔助虛擬化
 
-* [Docker](https://gitlab.com/libre-knowledge/docker)  
-  主流的容器實現之一
-* LXC
-* LXD
-* Oracle VirtualBox
-* Proxmox VE
-* QEMU
-* Xen
+* VT-x/AMD-V
+* VT-d
+* VT-c
+* AMD-Si
+* Extended Page Tables(Second Level Address Translation (SLAT))
 
-### 開發方案
+### 虛擬化資源編排工具
 
+* Docker Compose
 * Vagrant 開發環境建置與統合工具  
   快速建置相同的開發環境，避免團隊成員間環境不一致造成開發阻礙
 
 ## 參考資料
 
+以下列舉撰寫本主題內容時所參考的第三方資源：
+
 * [虛擬化 - 維基百科，自由的百科全書](https://zh.wikipedia.org/zh-tw/%E8%99%9B%E6%93%AC%E5%8C%96)  
   [Virtualization - Wikipedia](https://en.wikipedia.org/wiki/Virtualization)  
   維基百科條目
@@ -119,9 +112,21 @@
 * [QEMU - Wikipedia](https://en.wikipedia.org/wiki/QEMU)
 * [Hardware virtualization - Wikipedia](https://en.wikipedia.org/wiki/Hardware_virtualization)
 * [3.3. Hardware vs. Software Virtualization](https://docs.oracle.com/en/virtualization/virtualbox/6.0/admin/hwvirt.html)
+* [Understanding the Virtualization Spectrum - Xen](https://wiki.xenproject.org/wiki/Understanding_the_Virtualization_Spectrum)  
+  說明全虛擬化與伴虛擬化的差異，與 Xen 所支援的實作方式
+
+<!--
+（待補）
+
+## 子主題
+
+以下列舉本主題相關的主題：
+
+（待補）
+-->
 
 ---
 
-本主題為[自由知識協作平台](https://libre-knowledge.github.io/)的一部分，除部份特別標註之經合理使用(fair use)原則使用的內容外允許公眾於授權範圍內自由使用
+本主題為[自由知識協作平台](https://gitlab.com/libre-knowledge/libre-knowledge)的一部分，除部份特別標註之經合理使用(fair use)原則使用的內容外允許公眾於授權範圍內自由使用
 
-如有任何問題，歡迎於本主題的[議題追蹤系統](https://github.com/libre-knowledge/virtualization/-/issues)創建新議題反饋
+如有任何問題，歡迎於本主題的[議題追蹤系統](https://gitlab.com/libre-knowledge/virtualization/-/issues)創建新議題反饋

REUSE.toml

@@ -0,0 +1,19 @@
+# REUSE licensing information association file
+#
+# References:
+#
+# * REUSE.toml | REUSE Specification – Version 3.2 | REUSE
+#   https://reuse.software/spec-3.2/#reusetoml
+#
+# Copyright 2024 林博仁(Buo-ren Lin) <[email protected]>
+# SPDX-License-Identifier: CC-BY-SA-4.0+
+
+version = 1
+
+[[annotations]]
+path = [
+    "*.README.md",
+    "**/README.md"
+]
+SPDX-FileCopyrightText = '2024 自由知識協作平台貢獻者 <https://gitlab.com/libre-knowledge/libre-knowledge/-/issues>'
+SPDX-License-Identifier = 'CC-BY-SA-4.0+'