docs: 撰寫主題說明文件雛型

Signed-off-by: 林博仁(Buo-ren Lin) <buo.ren.lin@gmail.com>

.editorconfig

@@ -0,0 +1,66 @@
+# EditorConfig is awesome
+# http://EditorConfig.org
+#
+# This file is based on The Common EditorConfig Template project
+# https://github.com/the-common/editorconfig-template
+#
+# Copyright 2021 林博仁(Buo-ren, Lin) <buo.ren.lin@gmail.com>
+# SPDX-License-Identifier: WTFPL
+
+# This is the top-most EditorConfig file
+root = true
+
+# Common settings
+[*]
+end_of_line = lf
+indent_style = space
+indent_size = 4
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Git configuration files uses tabs as indentation units
+[/.git{modules,config}]
+indent_style = tab
+
+# Avoid git patch fail to apply due to stripped unmodified lines that contains only spaces
+[/.git/**]
+trim_trailing_whitespace = false
+
+# Makefiles for *Make
+[{Makefile,*.mk}]
+indent_style = tab
+
+# Markdown documents
+[*.{md,mkd,mkdn,markdown}]
+# Trailing whitespace means manual linebreaks
+trim_trailing_whitespace = false
+
+# Don't check indentation size as it can't handle intentional indentation
+# in list item after hardbreaks to align with the node markers, use
+# Markdownlint to check instead
+indent_size = unset
+
+[*.{diff,patch}]
+# Trailing whitespaces are unchanged lines in patch files
+trim_trailing_whitespace = false
+
+# Vagrant configuration file
+[Vagrantfile]
+indent_size = 2
+
+# yamllint configuration files
+[.yamllint]
+indent_size = 2
+
+# YAML documents
+[*.{yml,yaml}]
+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

@@ -0,0 +1,18 @@
+# Git path attributes configuration file
+#
+# References:
+#
+# * Git - Git Attributes
+#   https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes
+# * Git - gitattributes Documentation
+#   https://www.git-scm.com/docs/gitattributes
+#
+# Copyright 2024 林博仁(Buo-ren Lin) <buo.ren.lin@gmail.com>
+# SPDX-License-Identifier: CC-BY-SA-4.0
+
+# Avoid exporting development files to release archive
+/.* export-ignore
+/continuous-integration export-ignore
+
+# Keep editorconfig for ease of editing of product files
+/.editorconfig -export-ignore

.github/workflows/README.md

@@ -0,0 +1,10 @@
+# workflows
+
+Workflow definition files of the [GitHub Actions Continuous Integration(CI) service](https://github.com/features/actions)
+
+## Reference
+
+* [Features • GitHub Actions](https://github.com/features/actions)  
+  Product page
+* [GitHub Actions Documentation - GitHub Docs](https://docs.github.com/en/actions)  
+  Official documentation

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

@@ -0,0 +1,63 @@
+# 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 2024 林博仁(Buo-ren Lin) <buo.ren.lin@gmail.com>
+# SPDX-License-Identifier: CC-BY-SA-4.0
+name: Check potential problems in the project
+on:
+  push:
+    branches:
+      - '**'
+jobs:
+  check-using-precommit:
+    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: Check out content from the Git repository
+        uses: actions/checkout@v4
+
+      - name: Configure PyPI data cache to speed up continuous integration
+        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@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@v4
+        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
+
+      - name: Send CI result notification to the Telegram channel
+        uses: yanzay/notify-telegram@v0.1.0
+        if: always()
+        with:
+          chat: '@libre_knowledge_ci'
+          token: ${{ secrets.telegram_bot_api_token_ci }}
+          status: ${{ job.status }}

.github/workflows/release.yml

@@ -0,0 +1,74 @@
+# Release product and their build aritfacts
+#
+# References:
+#
+# * Workflow syntax for GitHub Actions - GitHub Docs
+#   https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions
+#
+# Copyright 2024 林博仁(Buo-ren Lin) <buo.ren.lin@gmail.com>
+# SPDX-License-Identifier: CC-BY-SA-4.0
+name: Release product and their build aritfacts
+on:
+  push:
+    tags:
+      - v*.*.*
+
+jobs:
+  release:
+    name: Release product and their build aritfacts
+    runs-on: ubuntu-20.04
+    steps:
+      - 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
+
+      - name: Determine the name of the Git tag
+        run: printf "release_tag=${GITHUB_REF##*/}\\n" >> $GITHUB_ENV
+
+      - name: Determine the release version string
+        run: printf "release_version=${release_tag#v}\\n" >> $GITHUB_ENV
+
+      - 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
+          ./continuous-integration/generate-build-artifacts.sh
+
+      - name: Generate the release description
+        run: ./continuous-integration/generate-release-description.sh
+
+      - name: Publish the release archive to the GitHub Releases
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ env.project_id }} ${{ env.release_version }}
+          files: |
+            ${{ env.release_id }}.tar*
+          body_path: .detailed_changes

.gitignore

@@ -0,0 +1,90 @@
+# Version Tracking Ignore Rules for Git VCS
+# https://git-scm.com/docs/gitignore
+#
+# Exclude files not suitable for version tracking in Git
+#
+# This file is based on The Common .gitignore Templates
+# https://github.com/the-common/gitignore-templates
+#
+# Copyright 2022 林博仁(Buo-ren, Lin) <buo.ren.lin@gmail.com>
+# SPDX-License-Identifier: CC-BY-SA-4.0
+
+# Don't track regular Unix hidden files
+.*
+
+# Do track Git configuration files
+!.git*
+
+# Do track EditorConfig configuration files
+# https://editorconfig.org/
+!.editorconfig
+
+# Do track pre-commit configuration files
+# https://pre-commit.com/
+!.pre-commit-config.yaml
+
+# Do track Markdownlint configuration files
+# https://github.com/DavidAnson/markdownlint
+!.markdownlint.*
+
+# Do track Drone CI configuration files
+# https://docs.drone.io/
+!.drone.yml
+
+# Do track yamllint configuration files
+!.yamllint
+
+# Do track REUSE configuration files
+# https://reuse.software/
+!.reuse/
+
+# Do track GitLab CI configuration file
+!/.gitlab-ci.yml
+
+# Don't track common backup filename extensions
+*~
+*.bak*
+*.backup*
+*.bk*
+*.old*
+*.orig*
+
+## Don't track common archive files
+*.7z
+*.bz2
+*.gz
+*.tar*
+*.xz
+*.zip
+
+# Don't track binary image files
+*.bmp
+*.jpg
+*.png
+
+# Don't track common export formats from Markdown
+*.doc?
+*.htm?
+*.pdf
+
+# Don't track common program output logs
+*.err
+*.error
+*.log
+*.out
+*.output
+
+# Don't track compiled Python code caches
+*.pyc
+
+# Don't track Vagrant runtime directories
+.vagrant/
+
+# Don't track GNU gettext message catalog template
+*.pot
+
+# Don't track GNU gettext machine-readable message catalogs
+*.mo
+
+# Don't track continuous integration virtual environments
+/continuous-integration/venv/

.gitlab-ci.yml

@@ -0,0 +1,66 @@
+# GitLab CI configuration file
+#
+# References:
+#
+# * `.gitlab-ci.yml` keyword reference | GitLab
+#   https://docs.gitlab.com/ee/ci/yaml/
+#
+# Copyright 2024 林博仁(Buo-ren Lin) <buo.ren.lin@gmail.com>
+# SPDX-License-Identifier: CC-BY-SA-4.0
+do-static-analysis:
+  stage: test
+  rules:
+    - if: $CI_COMMIT_TAG == null
+  needs: []
+  image: ubuntu:22.04
+  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
+    - ./continuous-integration/do-static-analysis.sh
+
+generate-build-artifacts:
+  stage: build
+  rules:
+    - if: $CI_COMMIT_TAG
+  needs: []
+  image: ubuntu:22.04
+  artifacts:
+    paths:
+      - ${CI_PROJECT_NAME}-*.tar*
+  script:
+    - ./continuous-integration/generate-build-artifacts.install-system-deps.sh
+    - ./continuous-integration/generate-build-artifacts.sh
+
+upload-release-assets:
+  stage: deploy
+  rules:
+    - if: $CI_COMMIT_TAG
+  needs:
+    - generate-build-artifacts
+  image: curlimages/curl:latest
+  script:
+    - ./continuous-integration/upload-gitlab-generic-packages.sh
+
+create-release:
+  stage: deploy
+  rules:
+    - if: $CI_COMMIT_TAG
+  needs:
+    - generate-build-artifacts
+    - upload-release-assets
+  image: registry.gitlab.com/gitlab-org/release-cli:latest
+  script:
+    - apk add bash git
+    - ./continuous-integration/generate-release-description.sh
+    - ./continuous-integration/create-gitlab-release.sh