Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

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

未关闭
  • 哪里不对？
#232 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
52/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
冷清
领域
cli, documentation

调研方向

等待 PR #208 合并，然后检查 .sources/icskills 子模块，并在列出的文档文件中 grep persistent actor。更新 checklist 中所述的 Motoko、migration、timer 和 mops 推荐指南，并确认子模块固定在 4713d1e，且没有更改范围之外的文件。

由索引模型根据 Issue 内容生成。

描述

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.

主要语言
JavaScript
星标
4
派生
5
平均合并
19 小时 51 分钟
30 天内合并 PR
27

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

dfinity/developer-docs 的其他 Issue

查看 dfinity/developer-docs 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。