Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Future-proofing the example code

Đang mở
#17 1 bình luận 1 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
30/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
git
Lĩnh vực
documentation, tooling

Hướng nghiên cứu

Bắt đầu trong thư mục preproc của repository và so sánh preprocessor đi kèm với links preprocessor mặc định của mdBook. Điều tra cách các commit được tham chiếu có thể vẫn truy cập được từ master và cách chọn các phần tệp cần đưa vào. Được xem là hoàn thành khi tutorial có thể lấy một phần mã inline từ một commit được chỉ định mà không phụ thuộc vào việc cập nhật thủ công lặp đi lặp lại.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Parts II and III will have the reader (and thus, the writer as well) working iteratively on a codebase. Where it gets iffy is that any change made to earlier lessons must be consistently reflected in later lessons. (This could happen for example because an earlier lesson is amended to make "room for" a later one, to update the syntax for a newer RGBDS version etc.)

Propagating these changes throughout the tutorial, where they would be presented "inline", would be a massive pain. Instead, I suggest the codebase should be checked out into Git, and inline code examples pulled from that repo.

This does get somewhat involved in several ways (e.g. ensuring that all referenced commits are reachable from the master branch, keeping referenced line numbers consistent when rebasing, etc.), but I think is essential if we want to avoid the tutorial irremediably bit-rotting in the longer term.

The concrete solution, I'd say, is to build a mdBook preprocessor (either stand-alone, or as part of the bundled one), that is able to include portions of files (like the default links preproc is able to), but picking a version of that file in a specific commit. libgit integration is desirable so as to avoid a ton of slow git checkouts, but not necessary—the priority is to it make work.

Ngôn ngữ chính
Assembly
Star
179
Fork
64
Merge trung bình
7 ngày 22 giờ
Pull request đã merge (30 ngày)
1

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

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của gbdev/gb-asm-tutorial

Tất cả issue của gbdev/gb-asm-tutorial

Issue tương tự

Thêm issue về Documentation

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.