Quy trình từ cài đặt đến Pull Request

Trang này giải thích quy trình từ cài đặt môi trường đến tạo Pull Request.

Cài đặt môi trường

Fork repository trên GitHub, sau đó clone repository đã fork về máy. (Nếu bạn có quyền commit trực tiếp thì không cần fork.)

shell
# Người dùng thông thường
git clone git@github.com:your-account/survival-typescript-vietnamese.git
# Người có quyền commit
git clone git@github.com:LeHoangTuanbk/survival-typescript-vietnamese.git

shell
# Người dùng thông thường
git clone git@github.com:your-account/survival-typescript-vietnamese.git
# Người có quyền commit
git clone git@github.com:LeHoangTuanbk/survival-typescript-vietnamese.git

Cài đặt các công cụ cần thiết:

shell
yarn

shell
yarn

Khởi động dev server:

shell
yarn start

shell
yarn start

Việc khởi động dev server mất khá nhiều thời gian. Hãy đợi và không dừng process.

Sau khi dev server khởi động, mở http://localhost:3000 trong trình duyệt.

Tạo branch

Tạo branch mới:

bash
git checkout -b ten-branch

bash
git checkout -b ten-branch

Không thể push trực tiếp vào branch master. Vì vậy cần thực hiện thay đổi trên branch riêng.

Tạo nội dung

Thêm trang mới

Thêm file Markdown mới vào thư mục docs:

shell
mkdir -p docs/category/subcategory
touch docs/category/subcategory/new-page.md

shell
mkdir -p docs/category/subcategory
touch docs/category/subcategory/new-page.md

Thêm đường dẫn trang mới vào sidebars.js. Đường dẫn không bao gồm extension .md.

sidebars.js
js
module.exports = {
  // ...
  tutorialSidebar: [
    {
      type: "category",
      label: "Category",
      items: [
        {
          type: "category",
          label: "Subcategory",
          items: [
            // highlight-next-line
            "category/subcategory/new-page",
          ],
        },
      ],
    },
  ],
};

sidebars.js
js
module.exports = {
  // ...
  tutorialSidebar: [
    {
      type: "category",
      label: "Category",
      items: [
        {
          type: "category",
          label: "Subcategory",
          items: [
            // highlight-next-line
            "category/subcategory/new-page",
          ],
        },
      ],
    },
  ],
};

Sau khi hoàn thành, bắt đầu chỉnh sửa file đã tạo.

Chỉnh sửa trang có sẵn

Tìm file cần chỉnh sửa trong thư mục docs và chỉnh sửa.

Di chuyển trang có sẵn

1. Di chuyển file hoặc đổi tên file.
2. Cập nhật đường dẫn trong sidebars.js.
3. Thêm cấu hình redirect từ URL cũ sang URL mới trong vercel.json.
4. Chạy yarn build để kiểm tra link hỏng.

Ví dụ, nếu di chuyển docs/tutorials/setup.md sang docs/getting-started/setup.md, sửa "tutorials/setup" thành "getting-started/setup" trong sidebars.js, và thêm cấu hình sau vào redirects trong vercel.json:

vercel.json
json
{ "source": "/tutorials/setup", "destination": "/getting-started/setup" }

vercel.json
json
{ "source": "/tutorials/setup", "destination": "/getting-started/setup" }

Sau các thay đổi, chạy yarn build để kiểm tra link hỏng.

Những điều cần biết khi chỉnh sửa nội dung

📄️ Chỉnh sửa bằng VS Code

VS Code là editor được khuyến nghị để chỉnh sửa file Markdown.

📄️ Markdown

Markdown ngoài cú pháp tiêu chuẩn còn có các specification được mở rộng riêng cho project này.

📄️ Cấu trúc file

Trang này giải thích cấu trúc thư mục và các file trong repository.

Commit

Sau khi chỉnh sửa, commit các thay đổi:

shell
git add docs/category/subcategory/new-page.md
git commit -m "Thêm trang mới"

shell
git add docs/category/subcategory/new-page.md
git commit -m "Thêm trang mới"

mẹo

Ví dụ commit message:

• Thêm trang "Type annotation"
• Thêm sample code vào trang "Function"
• Sửa lỗi chính tả

Kiểm tra nội dung

Kiểm tra code style

Sử dụng Prettier và markdownlint để sửa style Markdown và TypeScript trong code block:

shell
yarn markdownlint:fix
yarn prettier:fix

shell
yarn markdownlint:fix
yarn prettier:fix

mẹo

Với code block không muốn auto format bởi Prettier, thêm <!--prettier-ignore--> phía trước.

markdown
<!--prettier-ignore-->
```ts
type Code =
  | 1
  | 2
  | 3;
```

markdown
<!--prettier-ignore-->
```ts
type Code =
  | 1
  | 2
  | 3;
```

mẹo

Chi tiết về các lỗi markdownlint xem tại tài liệu markdownlint.

Commit kết quả kiểm tra

Xác nhận kết quả auto fix bằng diff:

shell
git diff

shell
git diff

mẹo

Để hoàn tác các thay đổi từ auto fix, dùng git checkout.

Nếu không có vấn đề với nội dung auto fix, commit:

shell
git add docs/category/subcategory/new-page.md
git commit --amend # Gộp vào commit trước đó

shell
git add docs/category/subcategory/new-page.md
git commit --amend # Gộp vào commit trước đó

Gửi Pull Request

cẩn thận

Trước khi gửi Pull Request, hãy cố gắng gộp các commit thành 1.

Push các thay đổi:

shell
git push -u origin ten-branch

shell
git push -u origin ten-branch

Khi tạo Pull Request, sử dụng chức năng liên kết issue bằng keyword của GitHub để liên kết issue tương ứng. Điều này có 2 mục đích: một là để theo dõi lịch sử của PR, hai là để tự động close issue khi PR được merge. Ví dụ, với PR giải quyết issue #123, viết keyword sau trong nội dung:

markdown
Close #123

markdown
Close #123

Đây là bước cần thiết trong quy trình làm việc.

📄️ Quy trình làm việc (Thảo luận trước khi tạo PR)

Quy trình làm việc - thảo luận trước khi tạo Pull Request.

Khi PR được tạo, CI sẽ chạy để kiểm tra code style. Nếu CI pass, maintainer sẽ merge. Nếu bạn có quyền merge, có thể tự merge sau khi kiểm tra kết quả CI.