docs(motoko): update guides for new icskills — --default-persistent-actors, inline migration, mops-cli

Đang mở
#232 1 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
52/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Ít trao đổi
Lĩnh vực
cli, documentation

Hướng nghiên cứu

Chờ PR #208 được merge, sau đó kiểm tra submodule .sources/icskills và grep persistent actor trong các tệp tài liệu được liệt kê. Cập nhật hướng dẫn được khuyến nghị về Motoko, migration, timer và mops như mô tả trong checklist, đồng thời xác minh submodule được ghim tại 4713d1e và không có tệp nào ngoài phạm vi bị thay đổi.

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

Mô tả

documentation enhancement

Background

The icskills submodule is currently pinned at 1d125a9; remote origin/main is at 4713d1e. That commit adds three new skills and substantially rewrites the existing motoko skill:

Skill Change
motoko Major overhaul: --default-persistent-actors is now the standard; dot notation (M0236) and implicit comparators (M0237) required; mixins added; moc 1.7.0 pinned
migrating-motoko New: (with migration = ...) inline syntax for one-shot state migrations
migrating-motoko-enhanced New: multi-step migration with a migrations/ directory and mops-managed --enhanced-migration flag
mops-cli New: full toolchain coverage (check, build, test, lint, migrate, toolchain)

Scope

This is a single PR that bumps the submodule from 1d125a9 to 4713d1e and updates the docs to match. The two must ship together: bumping without updating the docs would leave persistent actor in every code example while the pinned skill recommends plain actor {} with --default-persistent-actors.

Required changes

Bump icskills submodule
  • Pin .sources/icskills to 4713d1e
Add --default-persistent-actors and drop persistent actor from code examples

With the flag in mops.toml, plain actor { } works and all state is persistent by default. Keeping persistent actor in code examples while recommending the flag is contradictory.

[moc]
args = ["--default-persistent-actors", "-W=M0236,M0237,M0223"]
  • Add --default-persistent-actors to the recommended mops.toml setup in guides/backends/data-persistence.mdx, concepts/orthogonal-persistence.md, and guides/canister-management/lifecycle.mdx
  • Replace persistent actor with actor in all Motoko code examples (approx. 50 occurrences in 30+ files — grep first to get the full list)
  • Keep persistent actor only in explanatory prose where the keyword itself is being discussed

Files known to contain persistent actor in code blocks:

guides/backends/data-persistence.mdx
guides/backends/timers.mdx
guides/backends/certified-variables.md
guides/chain-fusion/bitcoin.mdx
guides/chain-fusion/ethereum.mdx
guides/chain-fusion/solana.mdx
guides/chain-fusion/exchange-rates.mdx
guides/canister-management/lifecycle.mdx
guides/canister-management/cycles-management.mdx
guides/security/canister-upgrades.md
guides/security/access-management.mdx
guides/canister-calls/inter-canister-calls.mdx
guides/canister-calls/parallel-inter-canister-calls.mdx
guides/digital-assets/ledgers.mdx
guides/authentication/internet-identity.mdx
references/application-canisters.md
Document (with migration = ...) inline migration syntax

The canister upgrade guides recommend avoiding preupgrade/postupgrade but say nothing about what to do when a field type changes or a field is renamed. That answer is now the inline migration syntax.

  • Add a "Changing persistent state" subsection to guides/canister-management/lifecycle.mdx covering (with migration = ...)
  • Update guides/security/canister-upgrades.md to reference the migration syntax for incompatible type changes
Update timer re-registration pattern

guides/backends/timers.mdx uses system func postupgrade to re-register timers. The new skill identifies timer IDs as the canonical transient var use case.

  • Update guides/backends/timers.mdx to present transient var as the preferred pattern and move postupgrade to a note for legacy or complex cases
Document mops CLI commands in developer tools

references/developer-tools.md mentions mops but not its primary commands.

  • Add coverage of mops check, mops build, mops test, mops lint, and mops migrate to references/developer-tools.md

Out of scope

  • postupgrade in certified-variables.md and certification.md: legitimate use for re-establishing certifications after upgrade, not data migration
  • docs/languages/motoko/: auto-synced from caffeinelabs/motoko, not manually edited

Prerequisite

Wait for PR #208 to merge before starting. Several affected files are modified by that PR.

Ngôn ngữ chính
JavaScript
Star
4
Fork
5
Merge trung bình
1 ngày 6 giờ
Pull request đã merge (30 ngày)
30

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 dfinity/developer-docs

Tất cả issue của dfinity/developer-docs

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.