Release-layer cache for `assemble` (deferred optimisation)

Đang mở
  • Có gì không ổn?
#6 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

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

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
github-actions
Lĩnh vực
ci-cd, devops

Hướng nghiên cứu

Đây là một tối ưu hóa được trì hoãn cho bước release-gather của assemble action, không phải là nhiệm vụ cần triển khai ngay. Trước tiên, hãy profiling một repository có nhiều bản release docs.zip để xác nhận rằng thời gian tải xuống và giải nén chiếm ưu thế so với việc liệt kê release hiện có bằng một lệnh gh api --paginate duy nhất; chỉ sau đó mới đánh giá một bundle actions/cache với khóa dựa trên tập tag bất biến đã được sắp xếp, đồng thời duy trì việc thu thập artifact và tái dựng từ nguồn bền vững.

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

Mô tả

Summary

Every deploy, the assemble action re-downloads and unzips every release's
docs.zip to reconstruct the released-version layer of the site. This is the one
recurring cost that scales with the number of releases. A GitHub Actions cache of the
immutable released-tags layer could skip those re-downloads. This is deliberately
not built yet — open this as a tracking issue and revisit only with profiling
evidence.

Why it is deferred (not built now)

  • The likely-dominant cost is the N sequential gh round-trips, not the
    downloads.     That is already addressed by listing all releases in one
    gh api --paginate repos/$repo/releases call (vs N gh release view), which is
    faster and simpler and needs no cache.
  • The benefit is zero at adoption. A freshly-migrated repo has no docs.zip
    releases yet; the saving grows only as releases accumulate. For a handful of
    releases it is within noise.
  • It is a real readability cost now for an unproven, future, N-dependent saving.

Bring it back only if profiling on a repo with many docs.zip releases shows the
download/unzip phase dominating.

Why it must be scoped to the immutable release layer (never the whole site)

GitHub cache semantics fight the obvious "cache the expanded site" idea:

  • Cache scoping is one-directional. A cache written on a branch is visible only
    to that branch and its descendants; the default branch's cache is the only one
    all other branches/PRs can restore, and writes never flow upward. So "active
    branches write their build into a shared cache" is impossible — which is exactly
    why branch/PR previews come from cross-run CI artifacts (gh run download),
    which do cross the run/branch boundary. A cache cannot replace artifact gathering
    for branches.
  • A cached site reintroduces drift. An accumulating tree never forgets a deleted
    branch/release unless actively pruned — the very keep_files problem the
    reconstruct-from-sources model kills. Letting deploy-pages replace the whole site
    every deploy is what makes deletion self-healing; a cached tree forfeits that.
  • A cache is never a source of truth. GH caches evict after 7 idle days (and
    under a 10 GB/repo LRU cap), so the full durable-source gather must exist
    regardless. The cache only ever accelerates it.

So cache only the released-tags layer, which is immutable and permanent.

Sketch of the implementation

A composite action can't express a dynamic per-tag cache step, so the realisation is
a single extracted-releases bundle dir (<tag>/html per release) behind one
actions/cache step:

  • Key docs-releases-v1-<hash of the sorted tag set> with restore-keys prefix
    docs-releases-v1-. Adding a release changes the key ⇒ the prefix restores the
    previous superset (every prior release), the gather loop downloads only the one new
    tag, and the post-step save stores the new superset.
  • Released docs.zip is immutable, so a restored tag dir is never stale (a deliberate
    --clobber re-upload is out of scope — bump the v1 prefix if ever needed). On a
    miss the loop falls back to gh release download + unzip as today.
  • Branches (incl. main) and open PRs stay fresh from CI artifacts every deploy.

It would be a transparent enhancement to the release-gather step, not a change to the
action's contract; correctness rests entirely on the durable sources whether or not a
cache hits.

Ngôn ngữ chính
JavaScript
Star
1
Fork
1
Merge trung bình
3 giờ 26 phút
Pull request đã merge (30 ngày)
1

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

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 DiamondLightSource/myst-version-switcher-plugin

Tất cả issue của DiamondLightSource/myst-version-switcher-plugin

Issue tương tự

Thêm issue về JavaScript

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.