本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- moja 全域
- 技術文件撰寫者：
- Tlazypanda
- 專案名稱：
- FLINT 技術新手上路指南說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
FLINT 提供的技術新手上路指南文件，說明如何透過技術新手上路指導新貢獻者使用，讓新貢獻者能從維護人員的最少支援輕鬆著手。
專案問題
以下列出與目前說明文件相關的最重大問題： - 整理了一系列本機設定指南操作說明，導致新貢獻者難以開始使用。 - 多個 FLINT 存放區缺少其用途的說明文件且彼此沒有連結，因此新手開發人員難以辨別要安裝哪個存放區。 - Windows 安裝記錄詳盡，但以 Linux 為基礎的安裝說明文件仍有改善空間。 - Git 工作流程目前不包含在說明文件中
建議採行的做法
此提案提供一項解決方案，可協助新貢獻者透過技術新手上路指導新協作者，讓他們只要取得維護人員提供的最低支援，就能輕鬆開始上手。具體做法如下：重構目前的說明文件，使其更容易上手，同時維護所有可用說明文件的中央獨立存放區。本專案分為三個階段： - 檢閱現有說明文件和重構：這個階段的目標在於查看目前的指南並進行重構，確保新貢獻者能夠輕鬆理解。此外，你也必須修改說明文件，確保說明文件能新增徽章、表情符號，以及標示「僅限初次使用」或「第一個問題」標籤的問題相關資訊，以便使用者更容易理解。- 建立獨立的文件存放區：這個階段的目標，是連結獨立存放區中，按照邏輯順序列出的所有說明文件。包括如何訂購捐款指南、專案設定操作說明和逐步指南。 - 新增開發人員專用的開發人員工作流程和社群網站：這個階段的目標是新增開發人員工作流程，其中包含 Git 貢獻指南、專案的技術架構、測試與品質確保指南。「提議的社群」網站將呈現單一頁面應用程式，其中顯示工作流程和初次製作者的問題，可由新的貢獻者聲明及所有貢獻者名單。 第 1 階段：查看現有說明文件並進行重構：
修改下列存放區的現行說明文件： - FLINT：目前的說明文件內容並不詳盡，且未提供必要程式庫的先後順序。逐步指示指南分為不同的 PDF 檔案，但如要整理成單一檔案，就變得簡單明瞭。此外，安裝指南可以指定至 Windows，但針對 Linux 安裝程序，您可以重新導向至 FLINT.docker 存放區。- FLINT.docker：目前的說明文件並未提供設定這個存放區的目的，該存放區是透過 docker 提供 FLINT 的 Linux 安裝。透過 Docker 的支援僅限於 Ubuntu 18.04 (Bionic Beaver)，但可以延伸至其他以 Linux 為基礎的發行版本。目前的說明文件必須強調依序設定 Dockerfile 的方式，以及透過 makefile 進行建構的充分資訊。- FLINT.example：目前的說明文件並未提供設定這個存放區的目的，目的是提供如何使用 FLINT 的範例。您可以設定不同的執行範例，根據特定指示順利執行不同的範例執行作業。我們也必須將這個存放區連結至主要的 FLINT 存放區，藉此讓使用者可以前往此處，查看範例的實際運作情形。
您必須在目前的說明文件中新增以下資訊： - Git 和 GitHub 使用：這包含如何分支、複製，然後為存放區設定遠端上游的逐步操作說明。此外，這項工具也會提供相關資訊，說明如何根據最新的主要執行個體進行重新建構，以及處理合併衝突。- 徽章和表情符號：目前的說明文件缺少徽章和表情符號，幫助新貢獻者感到備受重視，也比較不會感到困難重重。 - 新手入門/新手友善問題相關資訊：這些資訊可協助新貢獻者將新貢獻者重新導向到淺顯易懂的問題，並造訪社群網站。 - 關於匯入功能存放區的資訊：Import-me 存放區是快速啟動任何 Moja Global 存放區的基準範本。目前的說明文件並未提及相同的重要性。您必須更新這個檔案，以提及「Import-me」存放區，以及如何新增此範本，做為建立新存放區的範本。您也應該建立一套既定的程序，讓程式設計師為 Import-me 存放區建議其他功能。
第 2 階段：建立中央獨立的說明文件存放區：
代管平台所用的工具：
我們建議代管平台使用的工具是「閱讀說明文件」，原因如下：- - 在不同代管平台中獲得高排名。 - 推送修訂版本的自動更新 - 由於大型社群採用這個功能，您可以輕鬆設定及疑難排解支援 - 說明文件採用 reStructuredText 格式，並由 Sphinx 編譯輸出內容。
依照邏輯順序整理所有內容：
建議的內容順序如下：- - 開發人員說明文件簡介：本節將介紹 Moja Global 和 FLINT。- 貢獻：本節包含「貢獻內容的方式」(就程式碼/回報錯誤/翻譯/說明文件/機構化事件等) 和「程式碼執行程式碼」子章節。 - 開發設定：本節包含「Git 和 GitHub 工作流程」、「Windows 安裝」、「Linux 安裝」子章節，包含有關如何整合文件的「Git 和 GitHub 工作流程」和「Linux 安裝」的子章節。- 加入我們：本節將提供 Slack 頻道等多個社群論壇，以便與 Moja Global 聯絡及合作。
第 3 階段：新增開發人員工作流程和社群網站，以供新的貢獻者參考：
開發人員工作流程說明文件：
開發人員工作流程說明文件包含以下子節：
- 使用的技術堆疊/架構與程式碼中的各種模組：針對已導入技術堆疊、各種程式庫和模組的程式碼，熟悉新貢獻者的說明文件。
- 整合式測試和涵蓋範圍工具：隆重推出 CI/CD 管道工具進行測試、涵蓋率機器人和自動品質檢查，可用於測試程式碼。並提供測試失敗時應該採取的指引。
- 用於簡化工作流程的機器人 (例如 Zulipbot：設計要顯示的機器人內容範本)，並提供說明文件，讓使用者瞭解機器人，並藉由貢獻改善機器人設定。
- 手動測試及提交提取要求：提供說明文件，說明如何以特定標準手動測試提取要求，並在提交提取要求時上傳螢幕截圖/GIF 的結果。
- 提取要求審查指南應遵循以下規定：將特定團隊加上標記以進行審查，並在提取要求中加入「需要審查」之類的標籤，方便維護人員回覆。
社群網站：
社群網站提供以下功能：-
- 工作流程相關資訊：工作流程包含新貢獻者可開始執行的一系列動作，例如：領取第一個計時器問題，然後建立給其他人的第一個計時器問題，以及提供意見及審查提取要求，藉此協助他人。
- 「僅限第一個計時器」問題清單：專屬於新手或新貢獻者的問題清單。
- 過時問題清單：列出已久沒有處理的問題清單，可供貢獻者挑選。
- 協作者清單：提供目前為 Moja Global 存放區貢獻的貢獻者清單。
- 近期貢獻者：最近為 Moja Global 存放區貢獻的貢獻者清單。
- 加入即時通訊論壇的連結：您可以透過連結加入 Slack 社群，以便解決查詢問題，並進一步討論專案。