寫好問題

所有出色的專案都是以使用者意見為基礎。封鎖使用 GitHub 問題來追蹤意見回饋。本頁將詳細說明如何撰寫方便開發人員閱讀及回應的問題,以便處理您的錯誤報告/功能要求。

事前作業

有任何疑問嗎?

我們非常樂意聆聽你的問題!但 GitHub 問題對這些問題不甚理想。如有任何疑問,請前往我們的開發人員論壇。如果您詢問問題,就很有可能收到即時且完整的回應,因為有許多開發人員多年來都使用 Blockly!

檢查重複項目

在撰寫「任何」類型的問題之前,建議先確認是否有相符的問題。如有這件事,您就不必親自寫出它!因此,在開始寫字之前,請先搜尋重複或相關問題。

如果發現相符的問題,可以給予「喜歡」或加上詳述想法的註解。這對於錯誤報告和功能要求而言特別重要。如果開發人員發現某個問題明顯受到關注,表示問題很可能已解決。

回報錯誤

所以你以發現發現了錯誤?太好了!我們希望能夠收到錯誤報告,因為我們希望這個專案能盡可能穩定地執行。請按照下列步驟修正錯誤。

  1. 檢查重複項目
  2. 收集證據
  3. 找出問題
  4. 整合重現問題
  5. 提出原因
  6. 寫下您的問題!

收集證據

一般來說,錯誤資訊越豐富越好。建議您提供下列項目:

  • 如果錯誤造成視覺問題,螢幕截圖或 GIF 就非常實用。
  • 如果錯誤只會影響特定類型的區塊或工作區設定,程式碼範例就非常實用。
  • 如果無法在特定環境以外重現錯誤,代管網站便是絕佳選擇。

找出問題

在核心程式庫、外掛程式、範例和程式碼研究室之間,我們取得了許多 Blockly 程式碼。請明確說明問題發生的位置。

如果問題是核心問題,哪一個部分?例如工具箱、縮放控制項或程式庫區塊發生問題。請盡可能具體說明。

如果問題位於區塊式範例,請找出問題所在外掛程式、程式碼研究室或示例。如果您在多個位置發現同樣的錯誤,也請一併告訴我們。

強化繁殖力

除非錯誤可以重現,因此在提交問題前,請確定您有可靠的方法來解決問題。

您應該會看到一系列步驟清單,告知開發人員如何重現錯誤。例如:

  1. 開啟 X 程式碼研究室。
  2. 前往 Y 頁面。
  3. 執行 Z 範例程式碼。
  4. 觀察不良行為,看起來像 W。

如果您的問題位於 Blockly 核心,請嘗試在 playground 中重現問題。

提出原因

如果您認為錯誤發生的原因,請一併附上相關資訊。同樣地,請盡可能具體說明。

寫下您的問題!

屆時請撰寫錯誤報告。選取存放區:

請務必填寫問題範本的所有部分,包括此處未列出的區段。

感謝您向我們回報錯誤,並祝您來信愉快!

後續步驟

  • 您的錯誤報告會自動標記為分類。
  • Blockly 團隊的待命成員會查看內容,並可能提出釐清問題。他們也會新增標籤,以便整理各項錯誤。
  • 問題可能標示為「Help Wanted」(需要幫助),在這種情況下,您可以聲明問題並開始進行。
  • 我們可能會將問題指派給 Blockly 團隊成員,讓他們進行修正。
  • 問題可能會標上每季里程碑,藉此表示何時完成。
  • 這個問題可能會置於 Icebox 里程碑中,這表示我們無意在可預見的未來處理這個問題。
    • 這可能是發生頻率較低的問題,或含有已知解決方法的錯誤。
    • 你仍然可以處理冰箱問題。
  • 這個問題可能列在「Bug Bash Backlog」里程碑中,這表示該問題並不緊急,但我們仍會希望加以修正。
    • 在每季的尾聲,該團隊花了幾週的時間,努力處理 Bug Bash Backlog 里程碑所提取的錯誤。
  • 如有需要,系統可能會從 Blockly 核心移至區塊樣本 (或相反方向),
  • 這個問題可能已結案。

功能建議

有什麼部分需要調整,才能改善 Blockly 的品質嗎?您是否有關於外掛程式、範例或程式碼研究室的想法?也許您有很喜歡的擴充功能,接著找出改善的方向。如果是的話,您來對地方了!下列步驟可協助您建立效果良好的功能要求,以取得回應。

  1. 檢查重複項目
  2. 檢查需求條件
  3. 收集你的想法
  4. 撰寫功能要求!

檢查規定

我們希望讓每個想法都能進入這個存放區!但遺憾的是,我們只是人類,針對 Google 收到的要求類型製定了相關規範。

以下是每個不同專案類別的指南:

  • 塊狀核心
  • 外掛程式
  • 範例:說明如何只使用一或兩項 Blockly 功能。
  • 程式碼研究室:說明如何完成單一工作或實作單一行為。

但這些原則並不高效率,也不見得很快。這只是讓你在投入時間建構功能要求之前, 先瞭解我們需要改善的部分。

如果不確定某些內容是否合宜,請到開發人員論壇發文。另外請記住,即使不認同您的創意,我們還是很樂意協助您以第三方外掛程式或教學課程的形式建立該構想!

收集您的想法

提交相片之前,你的構想不一定是 100% 的堅果與圖表,但你應該對你們的想法有很深的瞭解。開始寫字前,請先思考以下幾個問題:

  • 為何需要這項功能?
  • 這項功能是否解決了問題?
  • 這項功能的目標對象為何?
  • 為什麼這項功能會為他們帶來好處?
  • 哪些替代選項可以達成相同目標?

瞭解這些要素後,您就可以開始提出完善的功能要求!

撰寫功能要求!

現在,您可以撰寫功能要求了。選取存放區:

請務必填寫問題範本的所有部分,包括此處未列出的區段。

感謝您提出功能要求,並祝您撰寫問題!

後續步驟

  • 系統會自動將您的功能要求標記為分類。
  • Blockly 團隊的待命成員會查看內容,並可能提出釐清問題。他們也會新增標籤,以便整理各項錯誤。
  • 這項功能可能會標示為「Help Wanted」,以便聲明擁有權並開始使用。
  • 這項功能可能會指派給 Blockly 團隊成員,以進行實作。
  • 如有需要,可以將功能要求從 Blockly 核心移至區塊樣本 (或相反方向)。
  • 功能要求可能會關閉,在這種情況下,您還是能選擇以第三方外掛程式的形式實作功能要求。