GitHub Wiki 發佈
將請求的材料發佈至儲存庫的現有 Wiki。保持內容產生與發佈流程分離:使用提供的頁面、報告與素材,並根據需要調整連結與導覽。遵循目標專案的規則,不要匯入其他專案的慣例。
確定目的地與範圍
- 從請求與儲存庫上下文解析 GitHub 主機、儲存庫、Wiki URL、原始檔與預期的頁面名稱。僅針對會實質改變發佈內容的未確定選擇進行提問。
- 區分準備工作與發佈。明確的發佈請求即授權指定的 Wiki 更新;不要針對相同動作再次提問。僅請求草稿或評估並未授權推送。
- 首先探索相關連接器的能力。如果它們無法充分管理 Wiki 內容與素材,請改用 Wiki 的獨立 Git 儲存庫。簡短說明此後備方案。一般的儲存庫 Contents API 無法處理 Wiki 儲存庫。
- 使用現有的已驗證連線或 Git 憑證驗證存取權。切勿將憑證嵌入 URL、頁面或保留的證據中。未經驗證的 404 錯誤並不能證明私人 Wiki 不存在。
- 如果 Wiki Git 儲存庫不存在,請檢查 Wiki 是否已停用,或是否需要透過 GitHub 建立第一個頁面。不要將啟用儲存庫功能或變更存取權限作為副作用。在可能的情況下使用授權的第一頁建立方式;否則報告具體的缺失先決條件。
準備一個限定的更新
若是透過 Git 發佈,請參閱 Git 程序。使用全新的暫存複本,探索其實際的預設分支,並在寫入前讀取現有的目標頁面、Home 與側邊欄。
- 將每個原始檔對應到一個目標頁面或素材。保留不相關的頁面、手動撰寫的章節與導覽。缺少原始檔並不代表刪除指令。僅在頁面屬於請求的更新範圍時才替換整個頁面;對於共用的 Home/側邊欄內容,使用精確的編輯。保留現有連結,避免在重複執行時產生重複的導覽項目。
- 明確以 UTF-8 編碼讀寫文字。逐位元組複製二進位素材。不要無聲地修正來源事實,或從不同的資料集重新整理報告。保留其實際的日期、來源與限制;僅在重新產生屬於範圍內時才使用適當的上游產生器。
- 重寫連結以指向 Wiki 的實際目的地。儲存庫相對連結在移動頁面後可能會失效。複製引用的素材或連結到可存取的儲存庫修訂版;不要留下本機路徑、未發佈的分支連結或無法存取的外部資源。
- Wiki 會將頁面檔案名稱顯示為其標題,因此如果頁面以自身的 H1 開頭,則會顯示兩次。刪除該 H1 並以頁面檔案名稱作為頁面名稱,僅在 H1 與頁面名稱刻意不同時(例如 Home)才保留 H1;將導覽更新為衍生的名稱。Home 在
/wiki路徑下提供服務,因此其相對連結解析時會位於 Wiki 外部:對圖像、頁面連結與側邊欄使用絕對的 Wiki URL。 - 使用支援的內嵌圖像,並帶有意義的替代文字。對於 HTML 報表或動畫/互動式圖表,當 Wiki 無法呈現時,提供有用的靜態預覽以及原始素材的連結。不要將可下載的 HTML 描述為在 Wiki 內提供的應用程式。在產生新圖稿屬於範圍內時,遵循專案特定的圖表工具;此技能不要求任何特定的產生器。
- 檢查本機連結與素材、具代表性的非 ASCII 文字,以及確切變更的路徑。檢查最終的 diff,確保沒有意外的刪除、覆寫的內容、憑證或產生的垃圾檔案。除非使用者或專案要求在應用程式儲存庫中保留來源,否則請將暫存複本與本機證據保留在應用程式儲存庫之外。
發佈與驗證
僅在使用者現有授權範圍內進行發佈。Wiki 更新並不授權推送應用程式分支、變更議題、部署網站、排程同步或安裝 CI。
- 僅提交預期的 Wiki 路徑,然後依照 Git 程序中的描述提取並合併並行變更。正常推送至 Wiki 的已發現預設分支。切勿強制推送以覆蓋其他寫入者的工作。
- 如果推送被拒絕,提取並檢查一次。整合相容的編輯並重新檢查完整的 diff。如果相同的衝突再次發生、無法解決意圖或存取失敗,則停止重試,並保留可復原的複本,附上精確的阻礙原因。失敗時不要刪除它。
- 驗證已發佈的提交是否與遠端 live 版本一致。僅有乾淨的工作目錄並不能證明本機提交已被推送。
- 在可用的情況下,透過已驗證的瀏覽器檢查實際提供的頁面:頁面文字、代表性的 Unicode、導覽、連結、圖像載入與可讀性。對於圖表,將呈現結果與來源事實進行比較。當內嵌預覽會遮蓋標籤時,檢查完整尺寸的圖像。修正範圍內觀察到的缺陷,並重新檢查受影響的內容。
- 如果無法進行已驗證的呈現檢查,請分別報告發佈與遠端驗證的結果,不要包括未執行的瀏覽器檢查。不要根據本機檔案、HTTP 回應或成功的推送來聲稱呈現檢查通過。
回報頁面 URL、已發佈的修訂版、重大變更、已執行的檢查以及任何未解決的限制。在仍有未發佈的工作時,保留復原路徑。不要新增新的核准關卡、內容結構、專案生命週期或測試機制。