New action: sync-notebooks (internal git) — standardize notebook publishing

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

Maintainer thường phản hồi trong vòng 1 ngày

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
48/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ệ
git, github-actions, shell
Lĩnh vực
ci-cd, devops, tooling

Hướng nghiên cứu

Bắt đầu với các bước «Prepare» và «Commit» trong lecture-jax/.github/workflows/publish.yml:101-122 và lecture-python.myst/.github/workflows/publish.yml:120-141, sau đó kiểm tra .github/workflows/test-actions.yml. action hoàn tất khi các smoke test của nó bao phủ các đường dẫn có thay đổi và commit rỗng, các input bị thiếu thất bại một cách rõ ràng, thông tin xác thực được xử lý an toàn và các output được ghi trong tài liệu được tạo ra.

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

Mô tả

enhancement

Feature request — a sync-notebooks composite action

Publishing executed notebooks to the companion <repo>.notebooks repo is hand-rolled per repo in publish.yml — two mechanisms, inconsistent pinning:

  • internal git clone + push — lecture-jax, lecture-python.myst, lecture-python-programming
  • cpina/github-action-push-to-another-repository — lecture-python-intro and lecture-python-advanced.myst at unpinned @main, continuous_time_mcs at @v1.7

A composite action gives one implementation, org-wide upgrades via a single tag bump, and no floating third-party dependency pushing with our service PAT. Consumer side is QuantEcon/workspace-lectures#12, Phase 1 of which is shipping this action — section D of the family tracker QuantEcon/workspace-lectures#31. The publish-gh-pages bump QuantEcon/workspace-lectures#11 is closed, superseded by section A there.

Sequencing — build it

CHANGELOG.md:365-374 (v0.6.0) and PLAN.md:173 record the opposite direction: eliminate the .notebooks repos for gh-pages notebooks plus theme-generated Colab URLs, gated on quantecon-book-theme#359 — zero comments since it opened 2026-02-09, while the theme repo stayed active (commits through 2026-08-06) and the .notebooks repos remain live production (Colab flat-directory constraint, #102). Build now; the eventual theme change deletes the step.

Design — internal git

Generalize the "Prepare … sync" + "Commit notebooks" steps at lecture-jax/.github/workflows/publish.yml:101-122 and lecture-python.myst/.github/workflows/publish.yml:120-141, rather than a marketplace push action — we keep control of auth, the empty-commit case and commit identity.

- uses: quantecon/actions/sync-notebooks@v0
  with:
    notebooks-dir: _build/jupyter
    destination-repo: QuantEcon/lecture-jax.notebooks
    github-token: ${{ secrets.QUANTECON_SERVICES_PAT }}
    # optional, with defaults:
    destination-branch: main
    commit-message: 'auto publishing updates to notebooks'
    git-user-name: 'QuantEcon Services'
    git-user-email: '[email protected]'

Outputs: committed (bool — commit/push happened) and commit-sha.

Behaviour & hardening
  • Internal git only — clone the destination, copy notebooks, commit, push.
  • Empty-commit guard — unchanged notebooks must exit 0; lecture-jax/.github/workflows/publish.yml:121 runs git commit with no git diff --staged --quiet guard, so an unchanged set errors nothing to commit mid-step.
  • Token out of the remote URL — use http.extraheader; lecture-jax/.github/workflows/publish.yml:113 embeds the PAT in the clone URL, where it lands in .git/config and error output.
  • Shallow clone (--depth 1) of the destination — the three internal-git consumers clone full history today; cpina already does --single-branch --depth 1.
  • Fail fast on a missing token or a missing/empty notebooks-dir, with a clear message.
  • Decide what happens to _notebook_repo/. QuantEcon/workspace-lectures#12 lists "drop the vestigial _notebook_repo copy" as a hardening item; that is wrong and must not be implemented. It is checked into all six source repos and holds README.md and environment.yml; for the three cpina consumers it is load-bearing — that action moves .git aside, rm -rfs the destination and copies source-directory wholesale (entrypoint.sh:101, :107, :139), so those two files in the companion repos come from this step. Copying only *.ipynb freezes them — add an input for extra files, or record dropping them as deliberate.

Smoke-test in .github/workflows/test-actions.yml, whose Action harness: all checks job is a required check on main; cover the changed and empty-commit paths — this pushes to another repo with a privileged PAT. Post-release @v0 is covered by the canary (#100).

Migrate all six repos above once released (QuantEcon/workspace-lectures#12). Interim, recorded there: SHA-pin the floating @main consumers lecture-python-intro/.github/workflows/publish.yml:126 and lecture-python-advanced.myst/.github/workflows/publish.yml:115; continuous_time_mcs/.github/workflows/publish.yml:110 is already @v1.7.

Ngôn ngữ chính
Shell
Star
0
Fork
1
Merge trung bình
18 giờ 51 phút
Pull request đã merge (30 ngày)
58

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

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 QuantEcon/actions

Tất cả issue của QuantEcon/actions

Issue tương tự

Thêm issue về Shell/Bash

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.