docs(531): document config-bound @Scheduled and @CmdCD timing (v6.3.0) - #99
Conversation
Framework issue UltiKits/UltiTools-Reborn#531 lets @scheduled read its period/delay (periodKey, delayKey) and @cmdcd its cooldown (key) from a module config key, in seconds. Documented in English and Chinese, as of v6.3.0, from the javadoc on the framework branch: - scheduled-tasks: new "Config-Bound Timing" section: attributes, load-time checks, reload semantics (keeps the task's place in its cycle), sync-only (#535), declared methods only (#532), modules only, api-version: 630. - cmd-executor: "Binding the cooldown to a config key" under Command cooldown (#command-cooldown anchor unchanged): 0 = no cooldown, a bound negative value refuses the module while a literal <= 0 disables it, running cooldowns keep their end time. - config-file: "Numeric fields": boxed Long/Float/Double now load whole numbers; float/Float cannot take a YAML decimal (#534); link to bindings. - module-versioning: "New annotation attributes": why a 6.2.x framework silently ignores the bindings and why api-version, not the pin, is the floor. - external-plugin-api: bindings are refused for External Plugin API plugins. Prose and inline code only; no new examples/ references, no version bumps. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014kpFuvCTBEwnU5jLfmwhka
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Deploying ultitools-dev-doc with
|
| Latest commit: |
b9060a1
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://55d742a6.ultitools-dev-doc.pages.dev |
| Branch Preview URL: | https://docs-531-config-bound-period.ultitools-dev-doc.pages.dev |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cfb8c6ec80
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ```java | ||
| @Getter | ||
| @Setter | ||
| @ConfigEntity("config/economy.yml") |
There was a problem hiding this comment.
These new Java examples are embedded separately in the Chinese and English pages, and their comments have already diverged by locale. Future API changes can therefore leave one translation with stale or uncompilable code. Put the examples under examples/src and include the same files from both pages with <<<; the same issue also occurs in the newly added @CmdCD snippets.
AGENTS.md reference: AGENTS.md:L81-L85
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Agreed that zh/en drift is a real problem; the examples/ move itself is deferred, not declined.
Why it cannot land on alpha. This repository's CONTRIBUTING.md, section "alpha 上可以写什么" (what may be written on alpha), lists this as one of two things still forbidden on alpha:
新增指向未发布 API 的
<<< @/../examples/...引用。examples/编译的是 Maven Central 上的正式版，这类引用在alpha上就会让examples-ci.yml变红。
(Adding a <<< @/../examples/... reference to an unreleased API. examples/ compiles against the release on Maven Central, so such a reference turns examples-ci.yml red already on alpha.)
examples/pom.xml pins <ultitools.version>6.2.5</ultitools.version>, and the config-bound @Scheduled / @CmdCD API from UltiKits/UltiTools-Reborn#531 exists only in 6.3.0-SNAPSHOT. Bumping that version on alpha is the other forbidden item (it is guarded by scripts/check-version-consistency.sh).
When it happens. At the 6.3.0 release, the alpha -> master archive step bumps examples/pom.xml to 6.3.0; the snippets move into examples/src and both pages include them with <<< in that same change. Tracked in #100.
What was done now. Measured every code block in the ten pages this PR touches, zh against en. scheduled-tasks.md (the page this thread is on) had no code drift: its pairs differ only in translated comments and the translated comment = / message strings. Real code drift was found in cmd-executor.md and config-file.md (leading blank lines only in en, suggest="..." spacing and a trailing space only in zh, irregular indentation of both @RunAsync examples only in zh). Fixed in 56a8da4: every pair now has identical code, with only comments and user-facing string literals translated.
Follows the updated javadoc of Scheduled.java, CmdCD.java and COMPATIBILITY.md on UltiKits/UltiTools-Reborn#536, in English and Chinese: - cmd-executor: a bound cooldown reloaded to 0 stamps no new cooldown; running cooldowns keep their end time and expire on their own. - scheduled-tasks, cmd-executor: a panel write that sets a bound key outside its binding range is refused like a @range violation, nothing written. - scheduled-tasks, cmd-executor, config-file: do not put a module @range on a bound field; a @range violation on /ul reload aborts the rest of the module's reload (#509), while the binding's own range keeps the running value with a WARNING. - scheduled-tasks: async = true is for literal timings only (#535). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The zh and en copies of several Java snippets had drifted in code, not just in comments: leading blank lines present only in en, `suggest="..."` without spaces and a trailing space only in zh, and two-space/irregular indentation of the `@RunAsync` examples only in zh. Both copies now carry identical code; only comments and user-facing string literals remain translated. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 56a8da475f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - 被绑定字段的类型不是 `int`、`long`、`Integer` 或 `Long`； | ||
| - 值为 `null`、小于 1 秒，或大于 107,374,182 秒（`Integer.MAX_VALUE / 20`，约 3.4 年）。`0` 不表示关闭。 | ||
|
|
||
| ### 重载时生效 |
There was a problem hiding this comment.
On the Chinese page, 重载时生效 is a predicate meaning “takes effect on reload,” rather than the required noun-phrase heading used by the rest of the documentation. Rename it to a nominal form such as 重载行为 so the new section follows the repository’s bilingual title convention.
AGENTS.md reference: AGENTS.md:L60-L73
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 195d055: ### 重载时生效 is now ### 重载行为. I swept every heading this pull request adds, in both languages, for the same class and found one more predicate: the @CmdCD subsection #### 绑定到配置项 in zh/guide/essentials/cmd-executor.md, renamed to #### 配置项绑定的冷却时间. The two links to its anchor, in zh/guide/advanced/scheduled-tasks.md and zh/guide/essentials/config-file.md, are updated with it. The English headings are gerund or noun phrases, which match the Checking an artifact form in AGENTS.md, so they are unchanged.
(This heading dates from cfb8c6e. The previous commit, 56a8da4, did not touch it.)
AGENTS.md requires headings to be noun phrases. Two zh headings added for #531 were predicates: `重载时生效` becomes `重载行为`, and the `@CmdCD` subsection `绑定到配置项` becomes `配置项绑定的冷却时间`. The two in-page links to the renamed `@CmdCD` anchor are updated with it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 195d05590a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | Registration | `@UltiToolsModule` + `registerSelf()` | `UltiToolsAPI.connect(this)` | | ||
| | i18n | `plugin.i18n("key")` available | Not available — use plain strings | | ||
| | Config entities | Full support (`@ConfigEntity`) | **Not available** — use Bukkit `getConfig()` | | ||
| | Config-bound `@Scheduled` / `@CmdCD` (v6.3.0+) | Supported, see [Config-Bound Timing](/guide/advanced/scheduled-tasks#config-bound-timing) | Refused, use literal `period` / `delay` / `value` | |
There was a problem hiding this comment.
When a reader uses the newly advertised config-bound annotations, the adjacent plugin.yml row still instructs them to declare api-version: 620, even though the added @Scheduled and @CmdCD sections state that 6.3.0 refuses such bindings below 630. Following this comparison table therefore causes the module to be rejected at load; qualify the version row as 630 for config-bound annotations (and 620 otherwise) in both locales.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in b9060a1, in both locales: the plugin.yml row now reads api-version: 620, or 630 when the module uses a config-bound @Scheduled / @CmdCD. I swept the other api-version: 620 mentions in the docs. The only remaining ones are the quick-start.md scaffolds in both locales, which use no binding, so they stay correct at 620. (This row dates from before this pull request; neither 56a8da4 nor 195d055 touched this file.)
The External Plugin API comparison table told every module to declare `api-version: 620`, while the same table and the `@Scheduled` / `@CmdCD` sections state that 6.3.0 refuses a module using a config binding below `630`. A reader following the table would have the module rejected at load. The row now reads `620`, or `630` when a config binding is used, in both locales. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
|
@codex review |
|
Codex Review: Didn't find any major issues. Already looking forward to the next diff. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
1 participant
Summary
Doc-sync for framework issue UltiKits/UltiTools-Reborn#531 (config-bound
@Scheduledperiod/delay and@CmdCDcooldown). Companion framework PR: UltiKits/UltiTools-Reborn#536.This PR deliberately targets docs
alpha, notmaster.masteris the released site served at dev.ultikits.com; this behaviour ships in v6.3.0, so it lands onalphaand reachesmasterin the release-timealpha→masterpromotion.Written from the javadoc of
Scheduled.javaandCmdCD.javaand theCOMPATIBILITY.mdsection "A floor no linker enforces" on the framework branch. Every page is updated in both English and Chinese with matching headings.guide/advanced/scheduled-tasksconfig/periodKey/delayKey, values in seconds, load-time checks (1 to 107,374,182 s,0is not "off"), reload semantics that keep the task's place in its cycle, sync only (#535), declared methods only (#532), modules only,api-version: 630guide/essentials/cmd-executor#command-cooldownanchor is unchanged.0= no cooldown; a bound negative value refuses the module while a literal value of 0 or less disables the cooldown; a running cooldown keeps the end time it was stamped withguide/essentials/config-fileLong/Float/Doublenow load whole numbers;float/Floatcannot take a YAML decimal (#534); links to both bindingsguide/advanced/module-versioningapi-version, not thepom.xmlpin, is the floorguide/advanced/external-plugin-apiProse, inline code blocks and
as of v6.3.0callouts only. No new<<< @/../examples/...references and no version bumps.Local verification
npm ci && npm run build: green, including dead-link checking. New in-page and cross-page anchors were checked against the built HTML, in both locales.bash scripts/check-bilingual-parity.sh: green.find docs/src -name '*.md' -print0 | xargs -0 bash scripts/check-container-length.sh: green under a UTF-8 locale, which is what CI uses. UnderLC_ALL=Cthe script flags 123 pre-existing Chinese callouts, because awk then counts bytes instead of characters.check-rendered-links.sh --clean,verify-sw.sh,npm run typecheck,check-root-doc-links.sh: green.Issue closure
None
🤖 Generated with Claude Code