diff --git a/.editorconfig b/.editorconfig index 4e41e32..77da454 100644 --- a/.editorconfig +++ b/.editorconfig @@ -4,7 +4,7 @@ # This file is based on The Common EditorConfig Template project # https://github.com/the-common/editorconfig-template # -# Copyright 2021 林博仁(Buo-ren, Lin) +# Copyright 2021 林博仁(Buo-ren, Lin) # SPDX-License-Identifier: WTFPL # This is the top-most EditorConfig file diff --git a/.gitattributes b/.gitattributes index d072302..cafb855 100644 --- a/.gitattributes +++ b/.gitattributes @@ -7,12 +7,12 @@ # * Git - gitattributes Documentation # https://www.git-scm.com/docs/gitattributes # -# Copyright 2023 林博仁(Buo-ren, Lin) -# SPDX-License-Identifier: CC-BY-SA-4.0 +# Copyright 2024 林博仁(Buo-ren Lin) +# SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects # 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 diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 8c03048..79eaba7 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -1,8 +1,8 @@ # workflows -放置 [GitHub Actions](https://github.com/features/actions) 的工作流程(workflow)定義檔 +Workflow definition files of the [GitHub Actions Continuous Integration(CI) service](https://github.com/features/actions) -## 參考資料
Reference +## Reference * [Features • GitHub Actions](https://github.com/features/actions) Product page diff --git a/.github/workflows/check-potential-problems.yml b/.github/workflows/check-potential-problems.yml index 018c486..d2cf0a9 100644 --- a/.github/workflows/check-potential-problems.yml +++ b/.github/workflows/check-potential-problems.yml @@ -1,45 +1,45 @@ -# 用來檢查專案中的潛在問題的 GitHub Actions 工作流程(workflow)定義檔 +# GitHub Actions workflow for checking potential problems in the project # -# 編輯參考： +# References: # # * Workflow syntax for GitHub Actions - GitHub Docs # https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions # -# Copyright 2022 林博仁(Buo-ren, Lin) -# SPDX-License-Identifier: CC-BY-SA-4.0 -name: 檢查專案中的潛在問題 +# Copyright 2024 林博仁(Buo-ren Lin) +# SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects +name: Check potential problems in the project on: push: branches: - '**' jobs: check-using-precommit: - name: 使用 pre-commit 檢查專案中的潛在問題 + name: Check potential problems using 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: 自版控庫取出內容 + - name: Check out content from the Git repository uses: actions/checkout@v4 - name: Configure PyPI data cache to speed up continuous integration - uses: actions/cache@v3 + uses: actions/cache@v4 with: key: ${{ runner.os }}-pip path: ${{ env.PIP_CACHE_DIR }} - name: >- Configure pre-commit data cache to speed up continuous integration - uses: actions/cache@v3 + uses: actions/cache@v4 with: key: pre-commit|${{ env.PY }}|${{ hashFiles('.pre-commit-config.yaml') }} path: ${{ env.PRE_COMMIT_HOME }} - name: >- Configure pre-built ShellCheck cache to speed up continuous integration - uses: actions/cache@v3 + uses: actions/cache@v4 with: key: ${{ runner.os }}-${{ runner.arch }}-shellcheck path: ${{ env.SHELLCHECK_DIR }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 48c3f2b..27fea2f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -5,8 +5,8 @@ # * Workflow syntax for GitHub Actions - GitHub Docs # https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions # -# Copyright 2023 林博仁(Buo-ren, Lin) -# SPDX-License-Identifier: CC-BY-SA-4.0 +# Copyright 2024 林博仁(Buo-ren Lin) +# SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects name: Release product and their build aritfacts on: push: @@ -66,7 +66,7 @@ jobs: run: ./continuous-integration/generate-release-description.sh - name: Publish the release archive to the GitHub Releases - uses: softprops/action-gh-release@v0.1.15 + uses: softprops/action-gh-release@v2 with: name: ${{ env.project_id }} ${{ env.release_version }} files: | diff --git a/.gitignore b/.gitignore index 7def9e9..41698a4 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,7 @@ # This file is based on The Common .gitignore Templates # https://github.com/the-common/gitignore-templates # -# Copyright 2022 林博仁(Buo-ren, Lin) +# Copyright 2022 林博仁(Buo-ren, Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects # Don't track regular Unix hidden files diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 9fc5987..8013dc3 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -5,7 +5,7 @@ # * `.gitlab-ci.yml` keyword reference | GitLab # https://docs.gitlab.com/ee/ci/yaml/ # -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects do-static-analysis: stage: test diff --git a/.markdownlint.yml b/.markdownlint.yml index b5663d5..9d16668 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -1,47 +1,49 @@ # Markdownlint(Node.js variant) configuration file # https://github.com/igorshubovych/markdownlint-cli#configuration # -# This file is based on The Common Markdownlint(Node.js variant) Configuration Templates project -# https://github.com/Lin-Buo-Ren/common-markdownlint-nodejs-config-templates +# This file is based on The Common Markdownlint(Node.js variant) +# Configuration Templates project +# https://github.com/the-common/markdownlint-nodejs-config-templates # -# Copyright 2021 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects # Inherit Markdownlint rules default: True -# Only allow consistent un-ordered list bullet style(allow alternations in sub-levels) -MD004: +# Only allow consistent un-ordered list bullet style(allow alternations +# in sub-levels) +ul-style: style: sublist # Only allow 4 spaces as indentation of lists -MD007: +ul-indent: indent: 4 # Only allow 2 spaces as linebreak sequence -MD009: +no-trailing-spaces: br_spaces: 2 # Disable line length limitation(not suitable with CJK context) -MD013: False +line-length: False # Allow missing padding blank line between the heading markup and the context -MD022: False +blanks-around-headings: False # Allow duplicated non-sibling heading text -MD024: +no-duplicate-heading: siblings_only: True # Allow missing padding blank line between a list and its context -MD032: False +blanks-around-lists: False # Allow using raw HTML markups as workarounds of deficiencies of Markdown -MD033: False +no-inline-html: False # 佔位字是要被替換掉的，為此規則之特例 -MD036: false +no-emphasis-as-heading: false # Allow using YAML front matter, while not require the definition of the # `title` property -MD041: +first-line-h1: front_matter_title: '.*' diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 452c1a9..c330cc6 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -5,7 +5,7 @@ # This file is based on The Common Pre-commit Framework Configuration Template # https://github.com/Lin-Buo-Ren/common-precommit-config-template # -# Copyright 2021 林博仁(Buo-ren, Lin) +# Copyright 2021 林博仁(Buo-ren, Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects repos: @@ -35,7 +35,7 @@ repos: # Check Markdown documents with Markdownlint(Node.js variant) # https://github.com/DavidAnson/markdownlint - repo: https://github.com/igorshubovych/markdownlint-cli - rev: v0.23.2 + rev: v0.34.0 hooks: - id: markdownlint diff --git a/.yamllint b/.yamllint index ba05db4..c0ba574 100644 --- a/.yamllint +++ b/.yamllint @@ -12,7 +12,7 @@ # This file is based on The Unofficial yamllint Configuration Templates # https://github.com/Lin-Buo-Ren/yamllint-configuration-templates # -# Copyright 2021 林博仁(Buo-ren, Lin) +# Copyright 2021 林博仁(Buo-ren, Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects rules: # Use this rule to control the number of spaces inside braces (`{` and `}`). diff --git a/README.md b/README.md index a1092d3..c719914 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,7 @@ ## 參考資料 -本章節列舉開發本專案期間所參考的第三方資料： +以下列舉撰寫本主題內容時所參考的第三方資源： * [Machine-readable debian/copyright file](https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/) 說明 REUSE DEP5 檔案的撰寫格式 diff --git a/continuous-integration/create-gitlab-release.sh b/continuous-integration/create-gitlab-release.sh index 51433d6..039ea1a 100755 --- a/continuous-integration/create-gitlab-release.sh +++ b/continuous-integration/create-gitlab-release.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # Create GitLab project release # -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects set \ diff --git a/continuous-integration/do-static-analysis.install-system-deps.sh b/continuous-integration/do-static-analysis.install-system-deps.sh index 650e0b0..623b649 100755 --- a/continuous-integration/do-static-analysis.install-system-deps.sh +++ b/continuous-integration/do-static-analysis.install-system-deps.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # System dependency installation logic for the static analysis program # -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects set \ -o errexit \ diff --git a/continuous-integration/do-static-analysis.sh b/continuous-integration/do-static-analysis.sh index 69ff394..be3faf4 100755 --- a/continuous-integration/do-static-analysis.sh +++ b/continuous-integration/do-static-analysis.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # Check potential problems in the project -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects set \ -o errexit \ diff --git a/continuous-integration/generate-build-artifacts.install-system-deps.sh b/continuous-integration/generate-build-artifacts.install-system-deps.sh index 7fbfbea..bee9a97 100755 --- a/continuous-integration/generate-build-artifacts.install-system-deps.sh +++ b/continuous-integration/generate-build-artifacts.install-system-deps.sh @@ -2,7 +2,7 @@ # Install system dependencies required for generating the project # build artifacts # -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects set \ diff --git a/continuous-integration/generate-build-artifacts.sh b/continuous-integration/generate-build-artifacts.sh index 67f6f11..471030b 100755 --- a/continuous-integration/generate-build-artifacts.sh +++ b/continuous-integration/generate-build-artifacts.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # Generate the project build artifacts # -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects set \ -o errexit \ @@ -20,6 +20,8 @@ if ! script="$( fi script_dir="${script%/*}" +project_dir="${script_dir%/*}" +project_dirname="${project_dir##*/}" if ! test -e "${script_dir}/venv"; then printf \ @@ -54,6 +56,15 @@ if ! pip show git-archive-all &>/dev/null; then fi fi +printf \ + 'Info: Determining the build datestamp...\n' +if ! datestamp="$(date +%Y%m%d-%H%M%S)"; then + printf \ + 'Error: Unable to determine the build datestamp.\n' \ + 1>&2 + exit 2 +fi + printf \ 'Info: Determining the project version...\n' git_describe_opts=( @@ -65,16 +76,17 @@ if ! version_describe="$( git describe \ "${git_describe_opts[@]}" )"; then + version_describe="unknown-${datestamp}" printf \ - 'Error: Unable to determine the project version.\n' \ + 'Warning: Unable to determine the project version, will use "%s" as a fallback.\n' \ + "${version_describe}" \ 1>&2 - exit 2 fi project_version="${version_describe#v}" printf \ 'Info: Generating the project archive...\n' -project_id="${CI_PROJECT_NAME:-"${project_id}"}" +project_id="${CI_PROJECT_NAME:-"${PROJECT_ID:-"${project_dirname}"}"}" release_id="${project_id}-${project_version}" git_archive_all_opts=( # Add an additional layer of folder for containing the archive diff --git a/continuous-integration/generate-release-description.sh b/continuous-integration/generate-release-description.sh index 45bc956..b6504d4 100755 --- a/continuous-integration/generate-release-description.sh +++ b/continuous-integration/generate-release-description.sh @@ -2,7 +2,7 @@ # Generate release description text to explain the changes between the # previous release # -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects set \ @@ -43,6 +43,9 @@ if test -v CI_COMMIT_TAG; then release_tag="${CI_COMMIT_TAG}" fi +git_log_opts=( + --format='format:* %s (%h) - %an' +) if test "${git_tag_count}" -eq 1; then printf \ 'Info: Only one release tag was detected, generating the release description text from the very beginning to the "%s" release tag...\n' \ @@ -104,9 +107,6 @@ else "${previous_git_tag}" \ "${release_tag}" \ 1>&2 - git_log_opts=( - --format='format:* %s (%h) - %an' - ) if ! detailed_changes_markup+="$( git log \ "${git_log_opts[@]}" \ diff --git a/continuous-integration/patch-github-actions-sudo-security-policy.sh b/continuous-integration/patch-github-actions-sudo-security-policy.sh index 5492007..dfdf381 100755 --- a/continuous-integration/patch-github-actions-sudo-security-policy.sh +++ b/continuous-integration/patch-github-actions-sudo-security-policy.sh @@ -8,7 +8,7 @@ # * Including other files from within sudoers | Sudoers Manual | Sudo # https://www.sudo.ws/docs/man/sudoers.man/#Including_other_files_from_within_sudoers # -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects # Configure the interpreter behavior to bail out during problematic diff --git a/continuous-integration/sudoers.d/90_allow_github_actions_default_envvars.sudoers b/continuous-integration/sudoers.d/90_allow_github_actions_default_envvars.sudoers index c188aa5..e20b749 100644 --- a/continuous-integration/sudoers.d/90_allow_github_actions_default_envvars.sudoers +++ b/continuous-integration/sudoers.d/90_allow_github_actions_default_envvars.sudoers @@ -7,7 +7,7 @@ # * Default environment - variablesVariables - GitHub Docs # https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables # -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects # Whether we are in an CI environment diff --git a/continuous-integration/upload-gitlab-generic-packages.sh b/continuous-integration/upload-gitlab-generic-packages.sh index 635061e..398d3d3 100755 --- a/continuous-integration/upload-gitlab-generic-packages.sh +++ b/continuous-integration/upload-gitlab-generic-packages.sh @@ -1,7 +1,7 @@ #!/usr/bin/env sh # Upload release packages as GitLab generic packages # -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects set \ diff --git a/docker-compose.yaml b/docker-compose.yaml new file mode 100644 index 0000000..9164a53 --- /dev/null +++ b/docker-compose.yaml @@ -0,0 +1,30 @@ +# Docker Compose configuration file +# +# References: +# +# * Compose Specification | Compose file reference | Reference | Docker Docs +# https://docs.docker.com/compose/compose-file/ +# +# Copyright 2024 林博仁(Buo-ren, Lin) +# SPDX-License-Identifier: CC-BY-SA-4.0 +name: subject-name +services: + # Environment for testing the subject + test-environment: + container_name: subject-name-test + hostname: subject-name-test + image: ubuntu:24.04 + volumes: + - type: bind + source: ./ + target: /project + environment: + - http_proxy + - https_proxy + - HTTP_PROXY + - HTTPS_PROXY + + # Set this environment variable to your local timezone settings + # for proper operation timestamp + #- TZ=CST-8 + command: sleep infinity diff --git a/real.gitattributes b/real.gitattributes index af1a06c..4c3dc26 100644 --- a/real.gitattributes +++ b/real.gitattributes @@ -7,7 +7,7 @@ # * Git - gitattributes Documentation # https://www.git-scm.com/docs/gitattributes # -# Copyright 2023 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects # Avoid exporting development files to release archive diff --git a/real.markdownlint.yml b/real.markdownlint.yml index fc7eb65..82a89d2 100644 --- a/real.markdownlint.yml +++ b/real.markdownlint.yml @@ -1,44 +1,46 @@ # Markdownlint(Node.js variant) configuration file # https://github.com/igorshubovych/markdownlint-cli#configuration # -# This file is based on The Common Markdownlint(Node.js variant) Configuration Templates project -# https://github.com/Lin-Buo-Ren/common-markdownlint-nodejs-config-templates +# This file is based on The Common Markdownlint(Node.js variant) +# Configuration Templates project +# https://github.com/the-common/markdownlint-nodejs-config-templates # -# Copyright 2021 林博仁(Buo-ren, Lin) +# Copyright 2024 林博仁(Buo-ren Lin) # SPDX-License-Identifier: CC-BY-SA-4.0 OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects # Inherit Markdownlint rules default: True -# Only allow consistent un-ordered list bullet style(allow alternations in sub-levels) -MD004: +# Only allow consistent un-ordered list bullet style(allow alternations +# in sub-levels) +ul-style: style: sublist # Only allow 4 spaces as indentation of lists -MD007: +ul-indent: indent: 4 # Only allow 2 spaces as linebreak sequence -MD009: +no-trailing-spaces: br_spaces: 2 # Disable line length limitation(not suitable with CJK context) -MD013: False +line-length: False # Allow missing padding blank line between the heading markup and the context -MD022: False +blanks-around-headings: False # Allow duplicated non-sibling heading text -MD024: +no-duplicate-heading: siblings_only: True # Allow missing padding blank line between a list and its context -MD032: False +blanks-around-lists: False # Allow using raw HTML markups as workarounds of deficiencies of Markdown -MD033: False +no-inline-html: False # Allow using YAML front matter, while not require the definition of the # `title` property -MD041: +first-line-h1: front_matter_title: '.*'