docs(motoko): update guides for new icskills — --default-persistent-actors, inline migration, mops-cli
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ả
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/icskillsto4713d1e
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-actorsto the recommendedmops.tomlsetup inguides/backends/data-persistence.mdx,concepts/orthogonal-persistence.md, andguides/canister-management/lifecycle.mdx - Replace
persistent actorwithactorin all Motoko code examples (approx. 50 occurrences in 30+ files — grep first to get the full list) - Keep
persistent actoronly 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.mdxcovering(with migration = ...) - Update
guides/security/canister-upgrades.mdto 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.mdxto presenttransient varas the preferred pattern and movepostupgradeto 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, andmops migratetoreferences/developer-tools.md
Out of scope
postupgradeincertified-variables.mdandcertification.md: legitimate use for re-establishing certifications after upgrade, not data migrationdocs/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
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- 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.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của dfinity/developer-docs
-
Độ khó 4/5 3-5 ngày Mức phù hợp với người mới 55/100
dfinity/developer-docs#281 ·
-
Độ khó 4/5 3-5 ngày Mức phù hợp với người mới 35/100
dfinity/developer-docs#279 ·
-
docs: cycle cost docs follow-up — ICP formula, worked example, instruction profiling, cost traps Đang mở
Độ khó 4/5 3-5 ngày Mức phù hợp với người mới 68/100
dfinity/developer-docs#274 ·
-
Độ khó 4/5 3-5 ngày Mức phù hợp với người mới 65/100
dfinity/developer-docs#228 ·
-
feat(bitcoin): add region markers to basic_bitcoin examples for stable developer workflow embeds Đang mởenhancement
Độ khó 4/5 3-5 ngày Mức phù hợp với người mới 52/100
dfinity/developer-docs#168 ·
Tất cả issue của dfinity/developer-docs
Issue tương tự
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 76/100
avniproject/avni-client#2135 ·
-
automated broken-link
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 85/100
-
agent/security hive/hosted-available-lke648397-260827-5n31 security
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 84/100
-
enhancement
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
babalae/bettergi-scripts-list#3674 ·
-
A-Release-Notes C-Editing D-Modest S-Ready-For-Implementation
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 72/100
bevyengine/bevy-website#2595 ·