Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
353 lines (258 loc) · 9.31 KB

CONTRIBUTING.md

File metadata and controls

353 lines (258 loc) · 9.31 KB

貢獻《初學者數據科學》

感謝您對《初學者數據科學》課程的貢獻感興趣！我們歡迎社群的貢獻。

目錄

行為準則

此專案採用了 Microsoft 開源行為準則。 欲了解更多資訊，請參閱 行為準則 FAQ 或聯絡 opencode@microsoft.com 提出其他問題或意見。

我可以如何貢獻？

回報錯誤

在建立錯誤報告之前，請檢查現有的問題以避免重複。當您建立錯誤報告時，請盡可能提供詳細資訊：

  • 使用清晰且描述性的標題
  • 描述重現問題的具體步驟
  • 提供具體範例（程式碼片段、截圖）
  • 描述您觀察到的行為以及預期的行為
  • 包含您的環境細節（作業系統、Python版本、瀏覽器）

建議改進

我們歡迎改進建議！提出建議時：

  • 使用清晰且描述性的標題
  • 提供詳細的建議描述
  • 解釋此改進的用途
  • 列出其他專案中類似的功能（如果適用）

貢獻文件

文件改進始終受到歡迎：

  • 修正拼寫和語法錯誤
  • 提高解釋的清晰度
  • 補充缺失的文件
  • 更新過時的資訊
  • 添加範例或使用案例

貢獻程式碼

我們歡迎以下程式碼貢獻：

  • 新增課程或練習
  • 修正錯誤
  • 改進現有的筆記本
  • 新增數據集或範例
  • 改進測驗應用程式

入門指南

先決條件

在貢獻之前，請確保您已具備以下條件：

  1. 一個 GitHub 帳戶
  2. 您的系統已安裝 Git
  3. 安裝了 Python 3.7+ 和 Jupyter
  4. 安裝了 Node.js 和 npm（針對測驗應用程式的貢獻）
  5. 熟悉課程結構

請參閱 INSTALLATION.md 以獲取詳細的設置指導。

Fork 和 Clone

  1. 在 GitHub 上 Fork 此倉庫
  2. 將您的 Fork 本地克隆： 
    git clone https://github.com/YOUR-USERNAME/Data-Science-For-Beginners.git
cd Data-Science-For-Beginners
  3. 添加上游遠端： 
    git remote add upstream https://github.com/microsoft/Data-Science-For-Beginners.git

建立分支

為您的工作建立新分支：

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

分支命名規範：

  • feature/ - 新功能或課程
  • fix/ - 錯誤修正
  • docs/ - 文件更改
  • refactor/ - 程式碼重構

貢獻指南

關於課程內容

在貢獻課程或修改現有課程時：

  1. 遵循現有結構：

    • README.md 包含課程內容
    • Jupyter 筆記本包含練習
    • 作業（如果適用）
    • 連結到前測和後測

  2. 包含以下元素：

    • 清晰的學習目標
    • 步驟式解釋
    • 帶註解的程式碼範例
    • 練習題以供練習
    • 其他資源的連結

  3. 確保可訪問性：

    • 使用清晰、簡單的語言
    • 為圖片提供替代文字
    • 包含程式碼註解
    • 考慮不同的學習風格

關於 Jupyter 筆記本

  1. 在提交之前清除所有輸出：

    jupyter nbconvert --clear-output --inplace notebook.ipynb

  2. 包含帶解釋的 Markdown 單元格

  3. 使用一致的格式：

    # Import libraries at the top
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

# Use meaningful variable names
# Add comments for complex operations
# Follow PEP 8 style guidelines

  4. 在提交之前完整測試您的筆記本

關於 Python 程式碼

遵循 PEP 8 風格指南：

# Good practices
import pandas as pd

def calculate_mean(data):
    """Calculate the mean of a dataset.
    
    Args:
        data (list): List of numerical values
        
    Returns:
        float: Mean of the dataset
    """
    return sum(data) / len(data)

關於測驗應用程式的貢獻

在修改測驗應用程式時：

  1. 本地測試：

    cd quiz-app
npm install
npm run serve

  2. 運行 linter：

    npm run lint

  3. 成功構建：

    npm run build

  4. 遵循 Vue.js 風格指南及現有模式

關於翻譯

在新增或更新翻譯時：

  1. 遵循 translations/ 資料夾中的結構
  2. 使用語言代碼作為資料夾名稱（例如，法語使用 fr）
  3. 保持與英文版本相同的檔案結構
  4. 更新測驗連結以包含語言參數：?loc=fr
  5. 測試所有連結和格式

拉取請求流程

提交之前

  1. 使用最新更改更新您的分支：

    git fetch upstream
git rebase upstream/main

  2. 測試您的更改：

    • 運行所有修改過的筆記本
    • 測試測驗應用程式（如果已修改）
    • 驗證所有連結是否有效
    • 檢查拼寫和語法錯誤

  3. 提交您的更改：

    git add .
git commit -m "Brief description of changes"

    撰寫清晰的提交訊息：

    • 使用現在時態（例如 "Add feature" 而非 "Added feature"）
    • 使用命令式語氣（例如 "Move cursor to..." 而非 "Moves cursor to..."）
    • 第一行限制在 72 個字元內
    • 在相關時引用問題和拉取請求

  4. 推送到您的 Fork：

    git push origin feature/your-feature-name

建立拉取請求

  1. 前往 倉庫
  2. 點擊 "Pull requests" → "New pull request"
  3. 點擊 "compare across forks"
  4. 選擇您的 Fork 和分支
  5. 點擊 "Create pull request"

PR 標題格式

使用清晰、描述性的標題，遵循以下格式：

[Component] Brief description

範例：

  • [Lesson 7] 修正 Python 筆記本導入錯誤
  • [Quiz App] 添加德語翻譯
  • [Docs] 更新 README，新增先決條件
  • [Fix] 修正可視化課程中的數據路徑

PR 描述

在您的 PR 描述中包含：

  • 內容：您做了哪些更改？
  • 原因：為什麼需要這些更改？
  • 方法：您如何實現這些更改？
  • 測試：您如何測試這些更改？
  • 截圖：對於視覺更改，請包含截圖
  • 相關問題：連結到相關問題（例如 "Fixes #123"）

審核流程

  1. 自動檢查將在您的 PR 上運行
  2. 維護者將審核您的貢獻
  3. 根據反饋進行修改，提交額外的更改
  4. 一旦獲得批准，維護者將合併您的 PR

PR 合併後

  1. 刪除您的分支：

    git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name

  2. 更新您的 Fork：

    git checkout main
git pull upstream main
git push origin main

風格指南

Markdown

  • 使用一致的標題層級
  • 在各部分之間包含空行
  • 使用帶語言指定的程式碼塊： 
    ```python
import pandas as pd
```
  • 為圖片添加替代文字：![Alt text](../../translated_images/zh-HK/image.4ee84a82b5e4c9e6651b13fd27dcf615e427ec584929f2cef7167aa99151a77a.png)
  • 保持合理的行長（約 80-100 字元）

Python

  • 遵循 PEP 8 風格指南
  • 使用有意義的變數名稱
  • 為函數添加文檔字符串
  • 在適當的地方包含類型提示： 
    def process_data(df: pd.DataFrame) -> pd.DataFrame:
    """Process the input dataframe."""
    return df

JavaScript/Vue.js

  • 遵循 Vue.js 2 風格指南
  • 使用提供的 ESLint 配置
  • 撰寫模組化、可重用的元件
  • 為複雜邏輯添加註解

檔案組織

  • 將相關檔案放在一起
  • 使用描述性的檔案名稱
  • 遵循現有的目錄結構
  • 不要提交不必要的檔案（例如 .DS_Store、.pyc、node_modules 等）

貢獻者授權協議

此專案歡迎貢獻和建議。大多數貢獻需要您同意貢獻者授權協議 (CLA)，聲明您有權並實際授予我們使用您的貢獻的權利。欲了解詳情，請訪問 https://cla.microsoft.com。

當您提交拉取請求時，CLA 機器人將自動判斷您是否需要提供 CLA 並適當地標記 PR（例如，標籤、評論）。只需按照機器人提供的指示操作即可。您只需在所有使用我們 CLA 的倉庫中執行一次此操作。

有問題嗎？

感謝！

您的貢獻使這個課程對所有人都更好。感謝您花時間貢獻！

免責聲明：
本文件已使用人工智能翻譯服務 Co-op Translator 進行翻譯。儘管我們致力於提供準確的翻譯，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於關鍵資訊，建議使用專業人工翻譯。我們對因使用此翻譯而引起的任何誤解或錯誤解釋概不負責。