Merge pull request #32 from ocftw/docs

新增開發說明文檔

.github/workflows/docs.yml

@@ -2,8 +2,8 @@ name: Sites-Docs
 on:
   push:
     branches:
-      - actions
       - main
+      - docs
 
 jobs:
   deploy:
@@ -22,6 +22,9 @@ jobs:
           mkdir mdbook
           curl -sSL $url | tar -xz --directory=./mdbook
           echo `pwd`/mdbook >> $GITHUB_PATH
+      - name: Install Preprocessors
+        run: |
+          cargo install mdbook-toc
       - name: Deploy GitHub Pages
         run: |
           # This assumes your book is in the root of your repository.

README.md

@@ -6,13 +6,13 @@ OSCVPass (Open Source Contributor VIP Pass) 開源貢獻者快速通關計畫，
 
 每年約有 150 - 230 位有效資格，其貢獻類型不僅止於程式碼的貢獻，也有來自開源推廣的努力。
 
-此 Github Repo 主要為「[已申請者專案列表](https://oscvpass.ocf.tw/)」，但也包含專案未來計畫與工作任務討論的地方。或是 OCF.tw 的 [slack](ocftw.slack.com/) **＃oscvpass** 頻道。
+此 Github Repo 主要為「[已申請者專案列表](https://oscvpass.ocf.tw/)」，但也包含專案未來計畫與工作任務討論的地方。或是 OCF.tw 的 [slack](https://ocftw.slack.com/) **#oscvpass** 頻道。
 
 ## 實習招募與志工夥伴
 
 目前 OSCVPass 專案在招募實習夥伴，請參考 OCF 的[實習佈告](https://blog.ocf.tw/2023/06/intern-oscvpass.html)。
 
-如果您對此專案有想法，也想參與貢獻成為志工，歡迎直接寄信到 [[email protected]](mailto:[email protected]) 標題開頭註明 **[OSCVPass]** 內文包含簡單的自我介紹與你的想法，我們會儘快回覆，感謝！
+如果您對此專案有想法，也想參與貢獻成為志工，歡迎直接寄信到 [[email protected]](mailto:[email protected]) 標題開頭註明 **[OSCVPass]** 內文包含簡單的自我介紹與您的想法，我們會儘快回覆，感謝！
 
 ## 工作流程
 

src/docs/book.toml

@@ -6,4 +6,8 @@ src = "src"
 title = "OSCVPass 開源貢獻者專案"
 
 [output.html]
-site-url = '/docs/'
+site-url = "/docs/"
+
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]

src/docs/src/README.md

@@ -1,22 +1,37 @@
-# Introduction
+# OSCVPass 開源貢獻者
 
-**OSCVPass** 開源貢獻者票是在臺灣開源社群大型活動中常見的優惠票券，只要向活動主辦方提交在開源領域各個專案的特殊貢獻，即可申請獲取。但參與不同活動往往得分次申請，除了麻煩還是麻煩。
+OSCVPass (Open Source Contributor VIP Pass) 開源貢獻者快速通關計畫，是讓貢獻者提出近一年在開源領域貢獻的證明申請，申請核准後取得一年的 OSCVPass 資格，可在合作的研討會活動參與取得回饋。
 
-為了免去繁瑣程序開放文化基金會發起 [OSCVPass 專案](https://ocf.tw/p/oscvpass/)提供認證程序機制，取得認證資格後即可在各大年會與研討會使用相關的回饋方案。
+每年約有 150 - 230 位有效資格，其貢獻類型不僅止於程式碼的貢獻，也有來自開源推廣的努力。
 
-## 如何申請
+## 申請資格
 
 請提供實際針對開源專案提供開發、推廣、或其他有助專案進展之貢獻相關證明，開源專案與您的參與須符合下列幾種情況：
 
 1. 申請者請提出近一年內（月份區間）開源貢獻。（例如此時為 2023/08/15，則可以為 2022/08/01 之後的貢獻申請）
-2. 開源專案意指專案成果以 [FSF](https://www.fsf.org/licensing/) 或 [OSI](https://opensource.org/licenses/) 認同之公眾授權條款釋出者。
-3. 你的開源專案的貢獻可以包含但不限是：寫/修 Code 的、寫/修文件的、發 ISSUE 的、籌劃推廣活動的、釋出 non-code 作品的。
+2. 開源專案意指專案成果以 [FSF] 或 [OSI] 認同之公眾授權條款釋出者。
+3. 您的開源專案的貢獻可以包含但不限是：寫/修 Code 的、寫/修文件的、發 ISSUE 的、籌劃推廣活動的、釋出 non-code 作品的。
 4. 所提出之貢獻，必須可以經由公開途徑查證（例如提供 GitHub、GitLab、Bitbucket 等公開專案平台上的討論紀錄、網址、commit log、信件文本、公開釋出之演講投影片紀錄等。）
 
+> **Note:** 如何申請請[參考說明](apply-for-oscvpass.md)。
+
 ## 社群
 
 目前 OSCVPass 持續招募社群志工協助申請流程、審核平台、後台管理等基礎建設的建製，歡迎參與！
 
+- OCF.tw 的 [slack][ocf_slack] **#oscvpass** 頻道。
+
+## 其他連結
+
+- 專案說明頁面：[https://ocf.tw/p/oscvpass/](https://ocf.tw/p/oscvpass/)
+- 申請表單：[https://forms.gle/j62bUmTy1hKKGm7n6](https://forms.gle/j62bUmTy1hKKGm7n6)
+- 已申請者專案列表：[https://oscvpass.ocf.tw/](https://oscvpass.ocf.tw/)
+
 ## 授權條款
 
-本文件內容以 Creative Commons [姓名標示 4.0 國際 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/deed.zh_TW) 釋出。
+本文件內容以 Creative Commons [姓名標示 4.0 國際 (CC BY 4.0)][cc_by] 釋出。
+
+[FSF]: https://www.fsf.org/licensing/
+[OSI]: https://opensource.org/licenses/
+[ocf_slack]: https://ocftw.slack.com
+[cc_by]: https://creativecommons.org/licenses/by/4.0/deed.zh_TW

src/docs/src/SUMMARY.md

@@ -1,9 +1,16 @@
 # Summary
 
-[Introduction](README.md)
+[OSCVPass 計畫簡介](README.md)
 
-- [申請]()
-  - [如何申請]()
-- [社群]()
-  - [如何參與]()
-  - [計畫藍圖]()
+- [申請](apply-for.md)
+  - [如何提出申請](apply-for-oscvpass.md)
+  - [申請時常見問題](apply-for-qa.md)
+  - [教學]()
+    - [如何使用授權條款]()
+    - [如何貢獻開源專案]()
+    - [如何推廣開源]()
+- [社群](community.md)
+  - [如何參與](community-contribute.md)
+  - [計畫藍圖](roadmap.md)
+  - [參與開發](development.md)
+- [推薦專案]()

src/docs/src/apply-for-oscvpass.md

@@ -0,0 +1,39 @@
+# 如何申請 OSCVPass
+
+申請 OSCVPass 的資格與申請前的確認。
+
+<!-- toc -->
+
+## 申請流程
+
+[![OSCVPass process flow](https://oscvpass.ocf.tw/img/oscvpass.svg)](https://oscvpass.ocf.tw/img/oscvpass.svg)
+
+- ➊ 申請 OSCVPass：透過[申請表單](https://forms.gle/j62bUmTy1hKKGm7n6)提交證明文件送出。
+- ➋ 審核委員：由志工組成的審核委員，每月排班協助審核申請案件。
+- ➌ 審核方式（通過）：恭喜，將寄送認證合格通知信。
+- ➍ 審核方式（補件、不通過）：審核委員會依基本審核標準與建議其補件方式，可參考[常見問題](apply-for-qa.md)。
+- ➎ 寄送審核結果通知信：將寄送通知信告知審核結果。
+- ➏ 收錄開源貢獻者資料庫：收錄審核通過名單，以利後續回饋方案的寄送。
+- ➐ 合作研討會：每年與 OSCVPass 合作的年會與研討會。
+- ➑ 專案貢獻頁面：將申請通過的貢獻成果呈現在[計畫首頁](https://oscvpass.ocf.tw/)。
+- ➒ 研討會宣傳：持續宣傳讓更多人知道計畫與申請。
+
+## 申請資格
+
+請提供實際針對開源專案提供開發、推廣、或其他有助專案進展之貢獻相關證明，開源專案與您的參與須符合下列幾種情況：
+
+1. 申請者請提出近一年內（月份區間）開源貢獻。（例如此時為 2023/08/15，則可以為 2022/08/01 之後的貢獻申請）
+2. 開源專案意指專案成果以 [FSF] 或 [OSI] 認同之公眾授權條款釋出者。
+3. 您的開源專案的貢獻可以包含但不限是：寫/修 Code 的、寫/修文件的、發 ISSUE 的、籌劃推廣活動的、釋出 non-code 作品的。
+4. 所提出之貢獻，必須可以經由公開途徑查證（例如提供 GitHub、GitLab、Bitbucket 等公開專案平台上的討論紀錄、網址、commit log、信件文本、公開釋出之演講投影片紀錄等。）
+
+## 申請前確認事項
+
+- [x] 是否在一年內的貢獻？
+- [x] 是否有在專案內宣告授權條款？
+- [x] 是否與開源領域相關的貢獻？
+- [x] 是否有在 [FSF]、[OSI] 認可的授權類型？
+- [x] 所提交的申請證明與申請人關聯是否為本人？
+
+[FSF]: https://www.fsf.org/licensing/
+[OSI]: https://opensource.org/licenses/

src/docs/src/apply-for-qa.md

@@ -0,0 +1,48 @@
+# 常見問題
+
+申請、補件、退件時常遇到的問題集合，預先閱讀可避免往返申請時程。
+
+<!-- toc -->
+
+## 申請
+
+### 不是程式貢獻是否可以申請
+
+可以，只要是開源領域相關的貢獻、不論方式為何，都歡迎提出申請！
+
+### 申請人與證明文件不相符合
+
+可先透過證明文件上的信箱發送到 [[email protected]](mailto:[email protected]) 並提及申請人的信箱來建立關聯。
+
+例如在 `git-commit` 所使用 `[email protected]` 提交，而申請人使用 `[email protected]` 提出申請，建議使用由 `[email protected]` 發出的郵件並提及 `[email protected]` 來建立關聯聲明。
+
+或使用在 Github 上 [sign-off commits][signoff_github] 的 PGP Key 直接簽署證明提交關聯聲明。
+
+#### 聲明範本
+
+    證明文件上所使用的郵件信箱：[email protected]
+    申請時所用的郵件信箱：[email protected]
+
+### 申請後未收到結果通知
+
+可能有幾種狀況：
+
+1. 由於審核委員皆為志工協助，目前並無固定的審核時間，請耐心等候。
+2. 近期有大量申請案件需要處理，也請耐心等候。
+3. 申請時所填寫的郵件信箱錯誤。
+
+如果等待時間超過申請時間約 14 天或以上，建議直接寄信到 [[email protected]](mailto:[email protected]) 詢問！
+
+### 申請表單 Google Forms
+
+目前我們已有[計畫](https://github.com/orgs/ocftw/projects/3)重構基礎建設，如果有興趣參與加入志工，歡迎喊聲、寄信或直接[開票](https://github.com/ocftw/OSCVPass/issues/2)給我們也行！
+
+## 退件、補件
+
+### 常見的退件或補件情況
+
+1. 所建立或所貢獻的專案沒有授權條款宣告，專案不是設定公開就代表 Open！
+2. 提交的證明文件與申請人找不到關聯，郵件信箱不同或是無法模糊比對為同一人！
+3. 重複申請或是自我專案重複貢獻（鼓勵多多踏出舒適圈或努力曝光專案的推廣）！
+
+[signoff_github]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits

src/docs/src/apply-for.md

@@ -0,0 +1,4 @@
+# 如何申請 OSCVPass
+
+1. [如何提出申請](apply-for-oscvpass.md)：申請簡介說明。
+2. [常見問題](apply-for-qa.md)：申請、退件、補件時常見的問題狀況。

src/docs/src/community-contribute.md

@@ -0,0 +1,31 @@
+# 如何貢獻
+
+目前 OSCVPass 計畫是由一群志工協助日常的申請、審核、通知與研討會接洽合作。
+
+<!-- toc -->
+## 流程現況
+
+[![OSCVPass process flow](https://oscvpass.ocf.tw/img/oscvpass.svg)](https://oscvpass.ocf.tw/img/oscvpass.svg)
+
+- ➊ 申請表單：目前是使用 Google Forms 作為申請表使用，但申請項目越來越多元，無法涵蓋表單的欄位定義與申請類型的情況。
+- ➋ 審核委員：目前審核委員由社群夥伴參與，一個月一名委員負責審核，但會因為當月其他因素無法在原定時間內審核完畢。
+- ➌➍ 審核方式（通過、補件、不通過）：目前審核的方式採取比較寬送的標準，無標準量化的機制。
+- ➎ 寄送審核結果通知信：通知信透過 AWS SES 大量寄送樣板信件。
+- ➏ 收錄開源貢獻者資料庫：目前是使用 Google Forms 表單標記已通過。
+- ➐ 合作研討會：每年參與的研討會。
+- ➑ 專案貢獻頁面：目前是使用靜態網頁呈現，問題在於整理與分類方式為人工手動方式進行。
+- ➒ 研討會宣傳：在各研討會宣傳申請計畫。
+
+## 招募志工
+
+計畫目前有兩種類型的志工需要協助，審核委員與專案志工。如有意願參與此計畫，歡迎直接來信到 [[email protected]](mailto:oscvpass.ocf.tw)，我們將協助建立相關設定。
+
+### 審核委員
+
+主要協助審核申請案件是否有達到基本的審核標準，簡單的審定標文件可以參考。目前每月會有一位值日生負責該月的申請案件，如該月份申請數量眾多，也可提出救援請求讓大家一起幫忙消化申請案件。
+
+### 專案志工
+
+主要負責改善審核流程、平台基礎工程、規劃宣傳或是其他概念的發想。參與的範圍不侷限流程圖上的項目，也可開拓新的領域來嘗試！
+
+> **Note:** 目前 OSCVPass 專案也在招募實習夥伴，請參考 OCF 的[實習佈告](https://blog.ocf.tw/2023/06/intern-oscvpass.html)。

src/docs/src/community.md

@@ -0,0 +1,4 @@
+# 社群
+
+1. [如何參與](community-contribute.md)：成為審核委員或是此計畫的籌備志工。
+2. [計畫藍圖](roadmap.md)：基礎工程重構計畫。

src/docs/src/development.md

@@ -0,0 +1,130 @@
+# 開發流程
+
+若要直接在docker上啟動環境，可以直接參見[在Docker上執行OSCVPass](#在Docker上執行OSCVPass)。
+
+<!-- toc -->
+
+## Pretalx建置 (用於Pretalx核心開發)
+
+> 本章節主要說明如何建置官方Pretalx的程式碼。
+
+完整建置流程可以參照[官方說明][official_build]
+
+### 前置作業
+
+需要先安裝以下工具：
+
+|工具|Debian套件名稱|
+|-|-|
+|python 3.6+||
+|pip 3|`python3-pip`|
+|python-dev 3|`python3-dev`|
+|python-venv 3|`python3-venv`|
+|libffi|`libffi-dev`|
+|gettext|`gettext`|
+|git|`git`|
+
+- 部分套件需要編譯器建置，若安裝失敗可先確認套件`build-essential`是否安裝。
+
+### 開啟虛擬Python環境
+
+```bash
+python3 -m venv env
+source env/bin/activate
+```
+
+- Ubuntu/Debian
+
+由於部分套件版本較舊，建議可先執行以下指令更新必要套件：
+
+```bash
+sudo pip3 install -U pip setuptools wheel
+```
+
+### 複製原始碼
+
+```bash
+git clone https://github.com/pretalx/pretalx.git
+cd pretalx/
+```
+
+### 初始環境建置
+
+首先安裝主程式所需要的相依函式庫：
+
+```bash
+(env)$ cd src
+(env)$ pip3 install --upgrade-strategy eager -Ue ".[dev]"
+```
+
+接著，複製靜態檔案至`STATIC_ROOTS`資料夾中，並初始化本地資料庫：
+
+```bash
+(env)$ python manage.py collectstatic --noinput
+(env)$ python manage.py migrate
+```
+
+為了能夠登入並操作，您需要創建至少一位具有管理員權限的帳號：
+
+```bash
+(env)$ python manage.py init
+```
+
+此外，若您開發上即刻需要一個用於測試的活動，您可以執行以下指令來創建：
+
+```bash
+(env)$ python manage.py create_test_event
+```
+
+### 語言檔案 (可選)
+
+由於Pretalx預設僅有英文語文檔案已經事前編譯完成，若您需要使用其他語言，您需要執行以下指令：
+
+```bash
+(env)$ python manage.py compilemessages
+```
+
+### 啟動環境
+
+```bash
+(env)$ python manage.py runserver
+```
+
+## 在Docker上執行OSCVPass
+
+> 本章節主要說明如何在本地端的docker上運行OSCVPass。
+
+詳細執行流程可以參照[pretalx-docker官方說明][official_docker]
+
+### 複製原始碼
+
+```bash
+$ git clone -b pretalx https://github.com/ocftw/OSCVPass.git
+$ cd OSCVPass/
+```
+
+### 直接執行
+
+- 運行測試環境
+
+```bash
+$ cd pretalx/
+$ docker compose -f ./docker-compose.yml up
+```
+
+- 運行生產環境
+
+```bash
+$ cd pretalx/
+$ docker compose -f ./docker-compose_prod.yml up
+```
+
+## 雜項
+
+- 關於GitHub上的分支
+  - main - 用於Github Pages上託管說明文檔
+  - docs - 用於暫存新版的說明文檔。
+  - pretalx - 用於儲存OSCVPass所使用的pretalx docker設定檔
+
+[official_build]: https://docs.pretalx.org/developer/setup.html
+[official_docker]: https://github.com/pretalx/pretalx-docker/README.md