|
|
# 貢獻《初學者數據科學》
|
|
|
|
|
|
感謝您對《初學者數據科學》課程的貢獻感興趣！我們歡迎社群的貢獻。
|
|
|
|
|
|
## 目錄
|
|
|
|
|
|
- [行為準則](../..)
|
|
|
- [我可以如何貢獻？](../..)
|
|
|
- [入門指南](../..)
|
|
|
- [貢獻指南](../..)
|
|
|
- [拉取請求流程](../..)
|
|
|
- [風格指南](../..)
|
|
|
- [貢獻者授權協議](../..)
|
|
|
|
|
|
## 行為準則
|
|
|
|
|
|
此專案採用了 [Microsoft 開源行為準則](https://opensource.microsoft.com/codeofconduct/)。
|
|
|
欲了解更多資訊，請參閱 [行為準則 FAQ](https://opensource.microsoft.com/codeofconduct/faq/) 或聯絡 [opencode@microsoft.com](mailto:opencode@microsoft.com) 提出其他問題或意見。
|
|
|
|
|
|
## 我可以如何貢獻？
|
|
|
|
|
|
### 回報錯誤
|
|
|
|
|
|
在建立錯誤報告之前，請檢查現有的問題以避免重複。當您建立錯誤報告時，請盡可能提供詳細資訊：
|
|
|
|
|
|
- **使用清晰且描述性的標題**
|
|
|
- **描述重現問題的具體步驟**
|
|
|
- **提供具體範例**（程式碼片段、截圖）
|
|
|
- **描述您觀察到的行為以及預期的行為**
|
|
|
- **包含您的環境細節**（作業系統、Python版本、瀏覽器）
|
|
|
|
|
|
### 建議改進
|
|
|
|
|
|
我們歡迎改進建議！提出建議時：
|
|
|
|
|
|
- **使用清晰且描述性的標題**
|
|
|
- **提供詳細的建議描述**
|
|
|
- **解釋此改進的用途**
|
|
|
- **列出其他專案中類似的功能（如果適用）**
|
|
|
|
|
|
### 貢獻文件
|
|
|
|
|
|
文件改進始終受到歡迎：
|
|
|
|
|
|
- **修正拼寫和語法錯誤**
|
|
|
- **提高解釋的清晰度**
|
|
|
- **補充缺失的文件**
|
|
|
- **更新過時的資訊**
|
|
|
- **添加範例或使用案例**
|
|
|
|
|
|
### 貢獻程式碼
|
|
|
|
|
|
我們歡迎以下程式碼貢獻：
|
|
|
|
|
|
- **新增課程或練習**
|
|
|
- **修正錯誤**
|
|
|
- **改進現有的筆記本**
|
|
|
- **新增數據集或範例**
|
|
|
- **改進測驗應用程式**
|
|
|
|
|
|
## 入門指南
|
|
|
|
|
|
### 先決條件
|
|
|
|
|
|
在貢獻之前，請確保您已具備以下條件：
|
|
|
|
|
|
1. 一個 GitHub 帳戶
|
|
|
2. 您的系統已安裝 Git
|
|
|
3. 安裝了 Python 3.7+ 和 Jupyter
|
|
|
4. 安裝了 Node.js 和 npm（針對測驗應用程式的貢獻）
|
|
|
5. 熟悉課程結構
|
|
|
|
|
|
請參閱 [INSTALLATION.md](INSTALLATION.md) 以獲取詳細的設置指導。
|
|
|
|
|
|
### Fork 和 Clone
|
|
|
|
|
|
1. **在 GitHub 上 Fork 此倉庫**
|
|
|
2. **將您的 Fork 本地克隆**：
|
|
|
```bash
|
|
|
git clone https://github.com/YOUR-USERNAME/Data-Science-For-Beginners.git
|
|
|
cd Data-Science-For-Beginners
|
|
|
```
|
|
|
3. **添加上游遠端**：
|
|
|
```bash
|
|
|
git remote add upstream https://github.com/microsoft/Data-Science-For-Beginners.git
|
|
|
```
|
|
|
|
|
|
### 建立分支
|
|
|
|
|
|
為您的工作建立新分支：
|
|
|
|
|
|
```bash
|
|
|
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. **在提交之前清除所有輸出**：
|
|
|
```bash
|
|
|
jupyter nbconvert --clear-output --inplace notebook.ipynb
|
|
|
```
|
|
|
|
|
|
2. **包含帶解釋的 Markdown 單元格**
|
|
|
|
|
|
3. **使用一致的格式**：
|
|
|
```python
|
|
|
# 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](https://www.python.org/dev/peps/pep-0008/) 風格指南：
|
|
|
|
|
|
```python
|
|
|
# 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. **本地測試**：
|
|
|
```bash
|
|
|
cd quiz-app
|
|
|
npm install
|
|
|
npm run serve
|
|
|
```
|
|
|
|
|
|
2. **運行 linter**：
|
|
|
```bash
|
|
|
npm run lint
|
|
|
```
|
|
|
|
|
|
3. **成功構建**：
|
|
|
```bash
|
|
|
npm run build
|
|
|
```
|
|
|
|
|
|
4. **遵循 Vue.js 風格指南**及現有模式
|
|
|
|
|
|
### 關於翻譯
|
|
|
|
|
|
在新增或更新翻譯時：
|
|
|
|
|
|
1. 遵循 `translations/` 資料夾中的結構
|
|
|
2. 使用語言代碼作為資料夾名稱（例如，法語使用 `fr`）
|
|
|
3. 保持與英文版本相同的檔案結構
|
|
|
4. 更新測驗連結以包含語言參數：`?loc=fr`
|
|
|
5. 測試所有連結和格式
|
|
|
|
|
|
## 拉取請求流程
|
|
|
|
|
|
### 提交之前
|
|
|
|
|
|
1. **使用最新更改更新您的分支**：
|
|
|
```bash
|
|
|
git fetch upstream
|
|
|
git rebase upstream/main
|
|
|
```
|
|
|
|
|
|
2. **測試您的更改**：
|
|
|
- 運行所有修改過的筆記本
|
|
|
- 測試測驗應用程式（如果已修改）
|
|
|
- 驗證所有連結是否有效
|
|
|
- 檢查拼寫和語法錯誤
|
|
|
|
|
|
3. **提交您的更改**：
|
|
|
```bash
|
|
|
git add .
|
|
|
git commit -m "Brief description of changes"
|
|
|
```
|
|
|
|
|
|
撰寫清晰的提交訊息：
|
|
|
- 使用現在時態（例如 "Add feature" 而非 "Added feature"）
|
|
|
- 使用命令式語氣（例如 "Move cursor to..." 而非 "Moves cursor to..."）
|
|
|
- 第一行限制在 72 個字元內
|
|
|
- 在相關時引用問題和拉取請求
|
|
|
|
|
|
4. **推送到您的 Fork**：
|
|
|
```bash
|
|
|
git push origin feature/your-feature-name
|
|
|
```
|
|
|
|
|
|
### 建立拉取請求
|
|
|
|
|
|
1. 前往 [倉庫](https://github.com/microsoft/Data-Science-For-Beginners)
|
|
|
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. 刪除您的分支：
|
|
|
```bash
|
|
|
git branch -d feature/your-feature-name
|
|
|
git push origin --delete feature/your-feature-name
|
|
|
```
|
|
|
|
|
|
2. 更新您的 Fork：
|
|
|
```bash
|
|
|
git checkout main
|
|
|
git pull upstream main
|
|
|
git push origin main
|
|
|
```
|
|
|
|
|
|
## 風格指南
|
|
|
|
|
|
### Markdown
|
|
|
|
|
|
- 使用一致的標題層級
|
|
|
- 在各部分之間包含空行
|
|
|
- 使用帶語言指定的程式碼塊：
|
|
|
````markdown
|
|
|
```python
|
|
|
import pandas as pd
|
|
|
```
|
|
|
````
|
|
|
- 為圖片添加替代文字：``
|
|
|
- 保持合理的行長（約 80-100 字元）
|
|
|
|
|
|
### Python
|
|
|
|
|
|
- 遵循 PEP 8 風格指南
|
|
|
- 使用有意義的變數名稱
|
|
|
- 為函數添加文檔字符串
|
|
|
- 在適當的地方包含類型提示：
|
|
|
```python
|
|
|
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 的倉庫中執行一次此操作。
|
|
|
|
|
|
## 有問題嗎？
|
|
|
|
|
|
- 查看我們的 [Discord 頻道 #data-science-for-beginners](https://aka.ms/ds4beginners/discord)
|
|
|
- 加入我們的 [Discord 社群](https://aka.ms/ds4beginners/discord)
|
|
|
- 查看現有的 [問題](https://github.com/microsoft/Data-Science-For-Beginners/issues) 和 [拉取請求](https://github.com/microsoft/Data-Science-For-Beginners/pulls)
|
|
|
|
|
|
## 感謝！
|
|
|
|
|
|
您的貢獻使這個課程對所有人都更好。感謝您花時間貢獻！
|
|
|
|
|
|
---
|
|
|
|
|
|
**免責聲明**：
|
|
|
本文件已使用人工智能翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。儘管我們致力於提供準確的翻譯，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於關鍵資訊，建議使用專業人工翻譯。我們對因使用此翻譯而引起的任何誤解或錯誤解釋概不負責。 |
