Chương trình học Bài 242 trên tổng số 250 · Dự án cuối khóa: Ship It (Đóng gói dự án của bạn)
Dự án cuối khóa: Ship It (Đóng gói dự án của bạn)

HƯỚNG DẪN + Chạy bằng một lệnh

Bạn có bố cục sạch sẽ và các bài kiểm tra thực tế. Bước cuối cùng là phần người đánh giá sẽ xem trước tiên: file README và một câu lệnh để chạy ứng dụng. Một dự án mất mười phút để đoán cách bắt đầu sẽ tạo cảm giác bị lỗi ngay cả khi nó chạy được. Một dự án bạn có thể clone và chạy chỉ với một dòng lệnh sẽ tạo cảm giác chuyên nghiệp ngay cả khi nó nhỏ. Cùng một mã nguồn nhưng ấn tượng hoàn toàn khác nhau.

README là một bản hợp đồng. Người đọc sẽ lướt từ trên xuống dưới và họ mong đợi một cấu trúc dễ đoán: tên dự án là tiêu đề, sau đó là cách cài đặt, rồi đến cách sử dụng, và cuối cùng là cách kiểm thử. Cụ thể, một README tốt có dòng tiêu đề cấp cao nhất (# Something), sau đó là các phần theo thứ tự này:

# Triage Copilot

## Setup
pip install -e .            # editable install
cp .env.example .env        # then paste your real key into .env

## Usage
python -m triage            # the one-command run

## Tests
pytest

Thứ tự rất quan trọng vì người đọc sẽ làm theo từng bước. Sử dụng trước Setup sẽ gây bối rối -> bạn không thể dùng thứ gì chưa cài đặt. Vì vậy bạn viết một bộ kiểm tra, validate_readme(text), cái mà trả về True chỉ khi một tiêu đề #  xuất hiện, tiếp theo là ## Setup, rồi ## Usage, rồi ## Tests, mỗi cái sau cái trước đó. Một phần bị thiếu, hoặc các phần sai thứ tự, sẽ trả về False. Mẹo là: duyệt qua các dòng một lần, giữ một "con trỏ" vị trí của bạn, và yêu cầu mỗi phần phải xuất hiện tại vị trí sau con trỏ.

Chạy bằng một câu lệnh. Lưu ý ## Usage dòng trên là một câu lệnh đơn. Đó là mục tiêu của một mục tiêu Makefile hoặc justfile như make run -> một câu lệnh dễ nhớ để khởi chạy dự án, để không ai phải nhớ toàn bộ lệnh gọi. Viết make_run(name) trả về chuỗi lệnh đó cho một dự án, ví dụ python -m triage (hoặc make run). Nó phải nhúng tên dự án, được chuẩn hóa giống như thư mục package, để một dự án khác sẽ cho ra một câu lệnh khác.

Hai lưu ý trung thực, không tính điểm cho repo thật. Đầu tiên, các bí mật: bước cp .env.example .env tồn tại vì key API thật của bạn nằm trong .env, cái mà bạn thêm vào .gitignore và never commit. Bạn chỉ commit .env.example -> hình dạng shape của cấu hình với các giá trị giả định. Làm rò rỉ key lên repo công khai là lỗi kinh điển của dự án portfolio. Thứ hai, deploying this: để đưa nó lên mạng bạn sẽ viết một Dockerfile nhỏ (copy repo, pip install, đặt lệnh chạy làm entrypoint) và push lên PaaS như Render, Railway, hoặc Fly. Phần đó không thể chạy hoặc được chấm điểm trong trình duyệt của bạn -> đó là việc của bạn khi bạn xuất bản. Nhấn Run để kiểm tra một README hoàn chỉnh và in ra lệnh chạy.

Đến lượt bạn

Viết hai phần xác định của một README tốt. validate_readme(text) trả về True nếu một tiêu đề #  cấp cao nhất xuất hiện, sau đó là ## Setup, rồi ## Usage, rồi ## Tests, mỗi phần sau phần trước (thiếu phần hoặc các phần sai thứ tự -> False). make_run(name) trả về chuỗi chạy một lệnh (ví dụ python -m <pkg> hoặc make run) có chứa tên dự án, được chuẩn hóa giống như thư mục package, vì vậy tên khác nhau sẽ cho ra lệnh khác nhau.

Bạn thấy vấn đề gì trong bài học này? Hãy báo cáo nó · Hỏi về bài học này

Bài tập này sẽ sớm mở.

Hoàn thành bài học trước đó để mở khóa bài này. Toàn bộ khóa học là miễn phí, không cần tài khoản, và bạn có thể đọc bài học này ngay bây giờ.