12 KiB

Raw Blame History

Đóng góp cho Data Science for Beginners

Cảm ơn bạn đã quan tâm đến việc đóng góp cho chương trình học Data Science for Beginners! Chúng tôi hoan nghênh sự đóng góp từ cộng đồng.

Mục lục

Quy tắc ứng xử

Dự án này đã áp dụng Quy tắc ứng xử mã nguồn mở của Microsoft.
Để biết thêm thông tin, hãy xem Câu hỏi thường gặp về Quy tắc ứng xử
hoặc liên hệ opencode@microsoft.com nếu bạn có thêm câu hỏi hoặc ý kiến.

Làm thế nào để đóng góp?

Báo cáo lỗi

Trước khi tạo báo cáo lỗi, vui lòng kiểm tra các vấn đề hiện có để tránh trùng lặp. Khi bạn tạo báo cáo lỗi, hãy cung cấp càng nhiều chi tiết càng tốt:

Sử dụng tiêu đề rõ ràng và mô tả
Mô tả các bước cụ thể để tái hiện vấn đề
Cung cấp ví dụ cụ thể (đoạn mã, ảnh chụp màn hình)
Mô tả hành vi bạn quan sát được và điều bạn mong đợi
Bao gồm thông tin về môi trường của bạn (Hệ điều hành, phiên bản Python, trình duyệt)

Đề xuất cải tiến

Chúng tôi hoan nghênh các đề xuất cải tiến! Khi đề xuất cải tiến:

Sử dụng tiêu đề rõ ràng và mô tả
Cung cấp mô tả chi tiết về cải tiến được đề xuất
Giải thích tại sao cải tiến này hữu ích
Liệt kê các tính năng tương tự trong các dự án khác, nếu có

Đóng góp cho tài liệu

Cải thiện tài liệu luôn được đánh giá cao:

Sửa lỗi chính tả và ngữ pháp
Cải thiện sự rõ ràng của các giải thích
Thêm tài liệu còn thiếu
Cập nhật thông tin lỗi thời
Thêm ví dụ hoặc trường hợp sử dụng

Đóng góp mã

Chúng tôi hoan nghênh các đóng góp mã bao gồm:

Bài học hoặc bài tập mới
Sửa lỗi
Cải tiến các notebook hiện có
Bộ dữ liệu hoặc ví dụ mới
Cải tiến ứng dụng quiz

Bắt đầu

Yêu cầu

Trước khi đóng góp, hãy đảm bảo bạn có:

Tài khoản GitHub
Git được cài đặt trên hệ thống của bạn
Python 3.7+ và Jupyter được cài đặt
Node.js và npm (đối với đóng góp ứng dụng quiz)
Hiểu biết về cấu trúc chương trình học

Xem INSTALLATION.md để biết hướng dẫn cài đặt chi tiết.

Fork và Clone

Fork repository trên GitHub

Clone fork của bạn về máy:

git clone https://github.com/YOUR-USERNAME/Data-Science-For-Beginners.git
cd Data-Science-For-Beginners

Thêm upstream remote:

git remote add upstream https://github.com/microsoft/Data-Science-For-Beginners.git

Tạo nhánh

Tạo một nhánh mới cho công việc của bạn:

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

Quy ước đặt tên nhánh:

feature/ - Tính năng hoặc bài học mới
fix/ - Sửa lỗi
docs/ - Thay đổi tài liệu
refactor/ - Tái cấu trúc mã

Hướng dẫn đóng góp

Đối với nội dung bài học

Khi đóng góp bài học hoặc chỉnh sửa bài học hiện có:

Tuân theo cấu trúc hiện có:
- README.md với nội dung bài học
- Notebook Jupyter với bài tập
- Bài tập (nếu có)
- Liên kết đến quiz trước và sau bài học
Bao gồm các yếu tố sau:
- Mục tiêu học tập rõ ràng
- Giải thích từng bước
- Ví dụ mã với chú thích
- Bài tập thực hành
- Liên kết đến tài nguyên bổ sung
Đảm bảo tính dễ tiếp cận:
- Sử dụng ngôn ngữ rõ ràng, đơn giản
- Cung cấp văn bản thay thế cho hình ảnh
- Bao gồm chú thích mã
- Cân nhắc các phong cách học tập khác nhau

Đối với Notebook Jupyter

Xóa tất cả đầu ra trước khi commit:

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

Bao gồm các ô markdown với giải thích

Sử dụng định dạng nhất quán:

# 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

Kiểm tra notebook hoàn toàn trước khi gửi

Đối với mã Python

Tuân theo hướng dẫn phong cách 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)

Đối với đóng góp ứng dụng quiz

Khi chỉnh sửa ứng dụng quiz:

Kiểm tra cục bộ:
```
cd quiz-app
npm install
npm run serve
```
Chạy linter:
```
npm run lint
```
Xây dựng thành công:
```
npm run build
```
Tuân theo hướng dẫn phong cách Vue.js và các mẫu hiện có

Đối với bản dịch

Khi thêm hoặc cập nhật bản dịch:

Tuân theo cấu trúc trong thư mục translations/
Sử dụng mã ngôn ngữ làm tên thư mục (ví dụ: fr cho tiếng Pháp)
Duy trì cấu trúc tệp giống như phiên bản tiếng Anh
Cập nhật liên kết quiz để bao gồm tham số ngôn ngữ: ?loc=fr
Kiểm tra tất cả liên kết và định dạng

Quy trình Pull Request

Trước khi gửi

Cập nhật nhánh của bạn với các thay đổi mới nhất:
```
git fetch upstream
git rebase upstream/main
```
Kiểm tra các thay đổi của bạn:
- Chạy tất cả notebook đã chỉnh sửa
- Kiểm tra ứng dụng quiz nếu đã chỉnh sửa
- Xác minh tất cả liên kết hoạt động
- Kiểm tra lỗi chính tả và ngữ pháp
Commit các thay đổi của bạn:
```
git add .
git commit -m "Brief description of changes"
```
Viết thông điệp commit rõ ràng:
- Sử dụng thì hiện tại ("Thêm tính năng" thay vì "Đã thêm tính năng")
- Sử dụng giọng điệu mệnh lệnh ("Di chuyển con trỏ đến..." thay vì "Di chuyển con trỏ đến...")
- Giới hạn dòng đầu tiên trong 72 ký tự
- Tham chiếu các vấn đề và pull request khi cần thiết

Push lên fork của bạn:

git push origin feature/your-feature-name

Tạo Pull Request

Truy cập repository
Nhấp vào "Pull requests" → "New pull request"
Nhấp vào "compare across forks"
Chọn fork và nhánh của bạn
Nhấp vào "Create pull request"

Định dạng tiêu đề PR

Sử dụng tiêu đề rõ ràng, mô tả theo định dạng sau:

[Component] Brief description

Ví dụ:

[Lesson 7] Sửa lỗi import notebook Python
[Quiz App] Thêm bản dịch tiếng Đức
[Docs] Cập nhật README với yêu cầu mới
[Fix] Sửa đường dẫn dữ liệu trong bài học trực quan hóa

Mô tả PR

Bao gồm trong mô tả PR của bạn:

Cái gì: Bạn đã thực hiện những thay đổi gì?
Tại sao: Tại sao những thay đổi này cần thiết?
Cách thực hiện: Bạn đã thực hiện thay đổi như thế nào?
Kiểm tra: Bạn đã kiểm tra thay đổi như thế nào?
Ảnh chụp màn hình: Bao gồm ảnh chụp màn hình cho các thay đổi trực quan
Vấn đề liên quan: Liên kết đến các vấn đề liên quan (ví dụ: "Fixes #123")

Quy trình xem xét

Kiểm tra tự động sẽ chạy trên PR của bạn
Người duy trì sẽ xem xét đóng góp của bạn
Giải quyết phản hồi bằng cách thực hiện các commit bổ sung
Khi được chấp thuận, người duy trì sẽ merge PR của bạn

Sau khi PR của bạn được merge

Xóa nhánh của bạn:

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

Cập nhật fork của bạn:

git checkout main
git pull upstream main
git push origin main

Hướng dẫn về phong cách

Markdown

Sử dụng cấp độ tiêu đề nhất quán
Bao gồm các dòng trống giữa các phần
Sử dụng khối mã với chỉ định ngôn ngữ:
```
```python
import pandas as pd
```
```
Thêm văn bản thay thế cho hình ảnh: ![Alt text](../../translated_images/vi/image.4ee84a82b5e4c9e6651b13fd27dcf615e427ec584929f2cef7167aa99151a77a.png)
Giữ độ dài dòng hợp lý (khoảng 80-100 ký tự)

Python

Tuân theo hướng dẫn phong cách PEP 8
Sử dụng tên biến có ý nghĩa
Thêm docstring cho các hàm

Bao gồm gợi ý kiểu khi thích hợp:

def process_data(df: pd.DataFrame) -> pd.DataFrame:
    """Process the input dataframe."""
    return df

JavaScript/Vue.js

Tuân theo hướng dẫn phong cách Vue.js 2
Sử dụng cấu hình ESLint được cung cấp
Viết các thành phần mô-đun, có thể tái sử dụng
Thêm chú thích cho logic phức tạp

Tổ chức tệp

Giữ các tệp liên quan cùng nhau
Sử dụng tên tệp mô tả
Tuân theo cấu trúc thư mục hiện có
Không commit các tệp không cần thiết (.DS_Store, .pyc, node_modules, v.v.)

Thỏa thuận cấp phép cho người đóng góp

Dự án này hoan nghênh các đóng góp và đề xuất. Hầu hết các đóng góp yêu cầu bạn
đồng ý với Thỏa thuận cấp phép cho người đóng góp (CLA) tuyên bố rằng bạn có quyền,
và thực sự cấp cho chúng tôi quyền sử dụng đóng góp của bạn. Để biết chi tiết, hãy truy cập
https://cla.microsoft.com.

Khi bạn gửi một pull request, CLA-bot sẽ tự động xác định liệu bạn có cần
cung cấp CLA hay không và trang trí PR một cách thích hợp (ví dụ: nhãn, bình luận). Chỉ cần làm theo
hướng dẫn được cung cấp bởi bot. Bạn chỉ cần làm điều này một lần trên tất cả các repository sử dụng CLA của chúng tôi.

Câu hỏi?

Kiểm tra Kênh Discord #data-science-for-beginners
Tham gia cộng đồng Discord của chúng tôi
Xem các vấn đề hiện có và pull request

Cảm ơn!

Sự đóng góp của bạn làm cho chương trình học này tốt hơn cho tất cả mọi người. Cảm ơn bạn đã dành thời gian để đóng góp!

Tuyên bố miễn trừ trách nhiệm:
Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI Co-op Translator. Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng các bản dịch tự động có thể chứa lỗi hoặc không chính xác. Tài liệu gốc bằng ngôn ngữ bản địa nên được coi là nguồn thông tin chính thức. Đối với các thông tin quan trọng, khuyến nghị sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm cho bất kỳ sự hiểu lầm hoặc diễn giải sai nào phát sinh từ việc sử dụng bản dịch này.

12 KiB Raw Blame History