以 Pull Requests 參與網誌編輯

Pull Requests 是一種間接 git 倉儲改版的模式. 在此展示如何利用 github 的拉回請求, 以及 Leo Editor 專案檔案的建立, 對機械設計專題網誌新增文章.

Fork 倉儲

希望使用 Github 的 Pull Requests 功能, 必須在 github 系統中, 先登記用戶帳號, 啟用帳號後登入, 然後以瀏覽器連線到希望 Pull Requests 的倉儲網址, 利用 fork 功能, 將該倉儲"互刻"(所謂互刻, 就是一種互相具有連結關係的倉儲複刻) 到所登錄的 github 帳號下.

接下來則建議對於該 forked (互刻) 的倉儲, 儘量 git clone 到近端改版之外, 並且每間隔一段時間, 利用 github 所提供的"反向 pull requests", 保持與原始倉儲版本的同步, 避免因版本差異過大的情況下, 提出 Pull Requests, 而提高合併衝突的困難度.

如前所述, 這篇網誌是由 github 帳號 scrum-1 所建立, 截至目前, scrum-1 用戶已經完成 fork project_site 倉儲的動作, 而且以 git clone 將機械設計專題複製到近端改版. 而改版前的第一要務就是確認近端倉儲所在的分支.

切換分支

因 project_site 在 github 上的 default branch 為 master, 因此 git clone 到近端之後, 必須利用 git checkout gh-pages 切換到 gh-pages 分之後, 才能在正確的工作目錄中進行改版, 之後提交推送, 也必須注意, 一定要指定 gh-pages 分支, 才能正確對 github pages 網誌內容改版.

其次, 因為 scrum-1 用戶代表 2017 年學號以 4042 開頭的學員, 因此先在 clone 下來的倉儲中, 利用 git checkout gh-pages 將工作目錄轉到 gh-pages 分之後, 新增 users/4042 與 content/4042 目錄, 並將其個人用戶所屬的 .leo 檔案存為 users/4042/scrum1.leo, 並且利用 Leo Editor 的節點指令 @path 與 @edit, 將個人所屬的 .md 檔案, 存在 content/4042 目錄中, 例如: 目前這篇網誌的 .md 檔案為 content/4042/scrum1_20161215.md

因為同屬 4042 專題學員的 .md 檔案都規劃存在 content/4042 目錄中, 因此要求各用戶將各自所寫的 .md 檔案名稱中冠上 github 帳號, 除了避免彼此覆蓋內容外, 也可以明確找出不同用戶所寫的網誌 .md 檔案.

圖檔管理

在 Pelican 網誌系統中管理文章中所引用的圖檔, 是一項大工程, 假如文章內容與所引用的圖檔都要全部納入分散式版本管理的架構, 方法之一是將專門存放圖檔的 project_site_files 倉儲 gh-page 分支設為 project_site gh-pages 分支的子模組, 然後兩個倉儲分別改版 (也就是不要在 project_site 的改版過程中企圖修改 project_site_files 子模組對應目錄下的檔案). 但是在兩個倉儲利用 pull requests 或者 git submodule update 的過程並非同步時, 近端無法即時看到納入 project_site_files 倉儲中的圖檔.

另外一個比較建議採用的方式則是兩個倉儲分開維護, 若參與協同的學員擁有 project_site_files 倉儲的管理權限 ,就必須先將近端引用的圖檔先推送到 project_site_files 的 gh-pages 分支, 然後在 .md 文章中, 直接引用圖檔的絕對目錄, 例如下圖:

以下的三個圖檔, 也是先放到 scrum-1 近端的 project_site_files gh-pages 分支工作目錄中之後 ,以

git add -A

git commit -m "add scrum1 20161215 picture files"

git push origin gh-pages

提交推送到 scrum-1 帳號所屬的 project_site_files 倉儲之後, 再建立 pull requests, 然後由 project_site_files 倉儲的管理者接受後合併版本 ,就可以直接以圖檔案的絕對 URL 引用如下:

網誌提交推送

一旦 scrum-1 學員完成 .md 的文章原始檔案編輯, 且透過近端 local-pelican 按鈕轉為 pelican 網誌 html 系統之後, 可以利用支援 IPv4 的 https-server 按鈕或支援 IPv6 的 ipv6-https-server 按鈕, 在近端以 https 檢視網誌後, 直接提交推送到 scrum-1 的 project_site 倉儲後進行 pull requests, 由於拉回請求的過程, 管理者除了必須納入 scrum-1 所新增的 .md 檔案外, 其餘都必須先在近端用 local-pelican 按鈕轉檔檢驗, 因此 scrum-1 無需在 pull requests 的流程中提交 gh-pages-pelican 按鈕所產生的遠端格式版本(多了 disqus 留言系統), 可以直接提交近端版本即可.

但是負責審核 pull requests 的管理學員, 除了在近端檢查機械設計專題的網誌改版內容之外, 必須記得在提交推送到 project_site 倉儲 gh-pages 分支之前, 利用 gh-pages-pelican 按鈕, 將 .md 檔案轉為遠端網誌格式, 否則 disqus 留言系統將無法正確呈現.

最後, scrum-1 學員一旦完成互刻 project_site 倉儲 gh-pages 分支的提交推送後, 即可針對 gh-pages 分支, 新增 pull requests, 接下來就是 project_site 倉儲管理端審核請求, 以及納入改版內容的流程.