diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5806eff..e0bccd4 100644 --- a/.github/workflows/docs.yml +++ b/.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. diff --git a/README.md b/README.md index 8738ffc..be0af61 100644 --- a/README.md +++ b/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)。 -如果您對此專案有想法,也想參與貢獻成為志工,歡迎直接寄信到 [hi@ocf.tw](mailto:hi@ocf.tw) 標題開頭註明 **[OSCVPass]** 內文包含簡單的自我介紹與你的想法,我們會儘快回覆,感謝! +如果您對此專案有想法,也想參與貢獻成為志工,歡迎直接寄信到 [hi@ocf.tw](mailto:hi@ocf.tw) 標題開頭註明 **[OSCVPass]** 內文包含簡單的自我介紹與您的想法,我們會儘快回覆,感謝! ## 工作流程 diff --git a/src/docs/book.toml b/src/docs/book.toml index 66bf850..e7a95bd 100644 --- a/src/docs/book.toml +++ b/src/docs/book.toml @@ -6,4 +6,8 @@ src = "src" title = "OSCVPass 開源貢獻者專案" [output.html] -site-url = '/docs/' \ No newline at end of file +site-url = "/docs/" + +[preprocessor.toc] +command = "mdbook-toc" +renderer = ["html"] \ No newline at end of file diff --git a/src/docs/src/README.md b/src/docs/src/README.md index cd22080..9ca7322 100644 --- a/src/docs/src/README.md +++ b/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 \ No newline at end of file diff --git a/src/docs/src/SUMMARY.md b/src/docs/src/SUMMARY.md index b03a4c9..b2846db 100644 --- a/src/docs/src/SUMMARY.md +++ b/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) +- [推薦專案]() \ No newline at end of file diff --git a/src/docs/src/apply-for-oscvpass.md b/src/docs/src/apply-for-oscvpass.md new file mode 100644 index 0000000..ef1b7c1 --- /dev/null +++ b/src/docs/src/apply-for-oscvpass.md @@ -0,0 +1,39 @@ +# 如何申請 OSCVPass + +申請 OSCVPass 的資格與申請前的確認。 + + + +## 申請流程 + +[![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/ diff --git a/src/docs/src/apply-for-qa.md b/src/docs/src/apply-for-qa.md new file mode 100644 index 0000000..40e4636 --- /dev/null +++ b/src/docs/src/apply-for-qa.md @@ -0,0 +1,48 @@ +# 常見問題 + +申請、補件、退件時常遇到的問題集合,預先閱讀可避免往返申請時程。 + + + +## 申請 + +### 不是程式貢獻是否可以申請 + +可以,只要是開源領域相關的貢獻、不論方式為何,都歡迎提出申請! + +### 申請人與證明文件不相符合 + +可先透過證明文件上的信箱發送到 [oscvpass@ocf.tw](mailto:oscvpass@ocf.tw) 並提及申請人的信箱來建立關聯。 + +例如在 `git-commit` 所使用 `github@example.com` 提交,而申請人使用 `gmail@example.com` 提出申請,建議使用由 `github@example.com` 發出的郵件並提及 `gmail@example.com` 來建立關聯聲明。 + +或使用在 Github 上 [sign-off commits][signoff_github] 的 PGP Key 直接簽署證明提交關聯聲明。 + +#### 聲明範本 + + 證明文件上所使用的郵件信箱:github@example.com + 申請時所用的郵件信箱:gmail@example.com + +### 申請後未收到結果通知 + +可能有幾種狀況: + +1. 由於審核委員皆為志工協助,目前並無固定的審核時間,請耐心等候。 +2. 近期有大量申請案件需要處理,也請耐心等候。 +3. 申請時所填寫的郵件信箱錯誤。 + +如果等待時間超過申請時間約 14 天或以上,建議直接寄信到 [oscvpass@ocf.tw](mailto:oscvpass@ocf.tw) 詢問! + +### 申請表單 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 \ No newline at end of file diff --git a/src/docs/src/apply-for.md b/src/docs/src/apply-for.md new file mode 100644 index 0000000..bad0296 --- /dev/null +++ b/src/docs/src/apply-for.md @@ -0,0 +1,4 @@ +# 如何申請 OSCVPass + +1. [如何提出申請](apply-for-oscvpass.md):申請簡介說明。 +2. [常見問題](apply-for-qa.md):申請、退件、補件時常見的問題狀況。 diff --git a/src/docs/src/community-contribute.md b/src/docs/src/community-contribute.md new file mode 100644 index 0000000..cc98d93 --- /dev/null +++ b/src/docs/src/community-contribute.md @@ -0,0 +1,31 @@ +# 如何貢獻 + +目前 OSCVPass 計畫是由一群志工協助日常的申請、審核、通知與研討會接洽合作。 + + +## 流程現況 + +[![OSCVPass process flow](https://oscvpass.ocf.tw/img/oscvpass.svg)](https://oscvpass.ocf.tw/img/oscvpass.svg) + +- ➊ 申請表單:目前是使用 Google Forms 作為申請表使用,但申請項目越來越多元,無法涵蓋表單的欄位定義與申請類型的情況。 +- ➋ 審核委員:目前審核委員由社群夥伴參與,一個月一名委員負責審核,但會因為當月其他因素無法在原定時間內審核完畢。 +- ➌➍ 審核方式(通過、補件、不通過):目前審核的方式採取比較寬送的標準,無標準量化的機制。 +- ➎ 寄送審核結果通知信:通知信透過 AWS SES 大量寄送樣板信件。 +- ➏ 收錄開源貢獻者資料庫:目前是使用 Google Forms 表單標記已通過。 +- ➐ 合作研討會:每年參與的研討會。 +- ➑ 專案貢獻頁面:目前是使用靜態網頁呈現,問題在於整理與分類方式為人工手動方式進行。 +- ➒ 研討會宣傳:在各研討會宣傳申請計畫。 + +## 招募志工 + +計畫目前有兩種類型的志工需要協助,審核委員與專案志工。如有意願參與此計畫,歡迎直接來信到 [oscvpass@ocf.tw](mailto:oscvpass.ocf.tw),我們將協助建立相關設定。 + +### 審核委員 + +主要協助審核申請案件是否有達到基本的審核標準,簡單的審定標文件可以參考。目前每月會有一位值日生負責該月的申請案件,如該月份申請數量眾多,也可提出救援請求讓大家一起幫忙消化申請案件。 + +### 專案志工 + +主要負責改善審核流程、平台基礎工程、規劃宣傳或是其他概念的發想。參與的範圍不侷限流程圖上的項目,也可開拓新的領域來嘗試! + +> **Note:** 目前 OSCVPass 專案也在招募實習夥伴,請參考 OCF 的[實習佈告](https://blog.ocf.tw/2023/06/intern-oscvpass.html)。 diff --git a/src/docs/src/community.md b/src/docs/src/community.md new file mode 100644 index 0000000..f17a33c --- /dev/null +++ b/src/docs/src/community.md @@ -0,0 +1,4 @@ +# 社群 + +1. [如何參與](community-contribute.md):成為審核委員或是此計畫的籌備志工。 +2. [計畫藍圖](roadmap.md):基礎工程重構計畫。 diff --git a/src/docs/src/development.md b/src/docs/src/development.md new file mode 100644 index 0000000..db8ff07 --- /dev/null +++ b/src/docs/src/development.md @@ -0,0 +1,130 @@ +# 開發流程 + +若要直接在docker上啟動環境,可以直接參見[在Docker上執行OSCVPass](#在Docker上執行OSCVPass)。 + + + +## 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 diff --git a/src/docs/src/roadmap.md b/src/docs/src/roadmap.md new file mode 100644 index 0000000..ba31b72 --- /dev/null +++ b/src/docs/src/roadmap.md @@ -0,0 +1,38 @@ +# 規劃藍圖 + + + +## 計畫緣起 + +OSCVPass 原來自 [COSCUP 開源貢獻方案](https://blog.coscup.org/2020/07/oscvpass.html),但因為 COSCUP 不再需要報名入場,因此將此方案貢獻給開放文化基金會 OCF 繼續規劃與執行。 + +不論是在 COSCUP 期間所執行的計畫或是移交給 OCF 的規劃,都是希望可以多多鼓勵大家參與開源文化的貢獻,不論是在程式碼的貢獻或是以開源精神、開放文化的方式產出的作品都會是 OSCVPass 所希望能回饋的貢獻者! + +## 流程說明 + +計畫流程大致上整理如下表,依運作流程項目解說,目前計畫面臨的問題與希望可以改善的下一步。 + +[![OSCVPass process flow](https://oscvpass.ocf.tw/img/oscvpass.svg)](https://oscvpass.ocf.tw/img/oscvpass.svg) + +- ➊ 申請表單:目前是使用 Google Forms 作為申請表使用,但申請項目越來越多元,無法涵蓋表單的欄位定義與申請類型的情況。 +- ➋ 審核委員:目前審核委員由社群夥伴參與,一個月一名委員負責審核,但會因為當月其他因素無法在原定時間內審核完畢。 +- ➌➍ 審核方式(通過、補件、不通過):目前審核的方式採取比較寬送的標準,無標準量化的機制。 +- ➎ 寄送審核結果通知信:通知信透過 AWS SES 大量寄送樣板信件。 +- ➏ 收錄開源貢獻者資料庫:目前是使用 Google Forms 表單標記已通過。 +- ➐ 合作研討會:每年參與的研討會。 +- ➑ 專案貢獻頁面:目前是使用靜態網頁呈現,問題在於整理與分類方式為人工手動方式進行。 +- ➒ 研討會宣傳:在各研討會宣傳申請計畫。 + +## 基礎工程 + +由於專案申請流程目前存在大量的手工操作程序,而累積的申請案件越來越多、也漸漸影響到每一次通知前的準備。因此在 2023 下半年度開始計畫重構目前計畫的基礎建設,優化其流程! + +近期進度: + +- 2023/08/01 目前 ➊ 已開始測試使用 Pretalx 來解決 ➋➌➍ 的流程優化問題。 + +### 工程進度 + +秉持著開放的精神,我們將目前重構的工程進度都回報在 [Project](https://github.com/orgs/ocftw/projects/3) 上,歡迎持續追蹤並給予我們建議,感謝! + +> **Note:** 可參考[如何參與](community-contribute.md)加入我們一起改善!