Draft: GeneralUpdate.Core documentation by JusterZhu · Pull Request #56 · GeneralLibrary/GeneralUpdate-Samples

JusterZhu · 2026-05-31T16:57:19Z

Summary

Draft documentation for GeneralUpdate.Core as the first component page in the non-firmware documentation plan.

Scope

Rewrites the base Core documentation page.
Syncs the Chinese i18n page with the base content.
Updates the English i18n page with an English draft.
Covers Core role, GeneralUpdateBootstrap, runtime roles, main updater samples, options, events, silent update, extension points, Tools relationship, and troubleshooting.

Related issues

Part of Documentation proposal: non-firmware component docs and dual-track cookbooks #45
Addresses Docs subtask: update GeneralUpdate.Core component documentation #47

Validation

git diff --check
Attempted Docusaurus production build; it remained in the optimization stage for an extended period, so this PR is opened as draft for content review first.

JusterZhu · 2026-05-31T17:17:58Z

Expanded the Core draft into an API-focused component reference: bootstrap methods, UpdateRequest/Builder properties, options, events, lifecycle hooks, reporting, auth/SSL, download source/policy/executor/pipeline/orchestrator, strategy extension, silent update options, and Tools relationship. Docusaurus build passed with
pm run build -- --no-minify.

JusterZhu · 2026-05-31T17:32:36Z

Added a detailed Core manifest section covering generalupdate.manifest.json: its purpose, generated schema, GeneralUpdate.Tools generation flow, Core loading APIs (ManifestInfo, AppMetadataDiscoverer), recommended configuration pattern, and version write-back behavior. The zh-Hans and en docs were updated and the Docusaurus build passes.

JusterZhu · 2026-05-31T17:32:44Z

Added a detailed Core manifest section covering generalupdate.manifest.json: its purpose, generated schema, GeneralUpdate.Tools generation flow, Core loading APIs (ManifestInfo, AppMetadataDiscoverer), recommended configuration pattern, and version write-back behavior. The zh-Hans and en docs were updated and the Docusaurus build passes.

JusterZhu · 2026-05-31T17:44:13Z

Added hook guidance for Linux/macOS permission scenarios: the Hooks section now explains using IUpdateHooks as an open extension point for chmod +x, permission repair, signature/authorization scripts, with examples for UnixPermissionHooks and a custom script adapter.

JusterZhu · 2026-05-31T17:44:24Z

Added hook guidance for Linux/macOS permission scenarios: the Hooks section now explains using IUpdateHooks as an open extension point for chmod +x, permission repair, signature/authorization scripts, with examples for UnixPermissionHooks and a custom script adapter.

JusterZhu · 2026-05-31T17:47:17Z

Removed the remaining driver-related DriverDirectory references from the GeneralUpdate.Core documentation so the Core page no longer implies driver update support. Disk-space DriveInfo code remains because it is only a precheck example, not driver functionality.

JusterZhu · 2026-05-31T17:47:31Z

Removed the remaining driver-related DriverDirectory references from the GeneralUpdate.Core documentation so the Core page no longer implies driver update support. Disk-space DriveInfo code remains because it is only a precheck example, not driver functionality.

JusterZhu · 2026-05-31T17:53:08Z

Clarified the manifest version write-back section: generalupdate.manifest.json now explains that Core treats the manifest as the local version state file and automatically updates ClientVersion / UpgradeClientVersion after successful updates, so developers do not need to write application code to maintain local version numbers.

JusterZhu · 2026-05-31T17:53:21Z

Clarified the manifest version write-back section: generalupdate.manifest.json now explains that Core treats the manifest as the local version state file and automatically updates ClientVersion / UpgradeClientVersion after successful updates, so developers do not need to write application code to maintain local version numbers.

JusterZhu · 2026-05-31T18:30:23Z

Updated the draft Core documentation with the latest component-level details:

Added a topic map with stable anchors for strategy, differential, concurrency, events, logging, and manifest topics.
Expanded standard, OSS, and silent update strategy explanations based on current Core behavior.
Deepened differential algorithms, Clean/Dirty phases, download concurrency, and parallel patch processing.
Clarified generalupdate.manifest.json as the minimal-configuration path: Tools generates stable app identity metadata, while application code only supplies runtime/sensitive values such as endpoints and secrets.
Expanded event callback documentation from the current event implementations, including UpdateInfo, precheck skip semantics, progress, download completion/error, and exception notifications.
Added logging/performance guidance and how to disable tracing.

Validation: Docusaurus build passes for zh-Hans and en.

JusterZhu · 2026-05-31T18:37:00Z

Updated the event callback section to clarify AddListenerUpdatePrecheck:

It is not only a skip/continue decision point before download; it also receives the current update's VersionEntry list through UpdateInfoEventArgs.
The docs now explain using that information to build a release-notes/update-content dialog so users can decide whether to continue the update.
The sample now reads Info.Body, shows a user confirmation hook, and keeps the current return semantics clear: true skips a non-forced update, false continues.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR drafts a new, significantly expanded documentation page for GeneralUpdate.Core and syncs that content across the base docs plus English and Chinese i18n copies, aligning the page with the “non-firmware component docs” plan (Core as the first component page).

Changes:

Rewrites the GeneralUpdate.Core page structure with a topic map, strategy overview (standard/OSS/silent), and a deeper API/extension-point walkthrough.
Adds detailed sections for UpdateRequest, generalupdate.manifest.json, events, logging controls, differential pipeline concepts, and tooling relationship.
Updates both website/i18n/en/... and website/i18n/zh-Hans/... copies to mirror the new base content.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 9 comments.

File	Description
website/docs/doc/GeneralUpdate.Core.md	New Core component draft: strategies, configuration, diff pipeline, events, and extension points.
website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md	English i18n draft synced to the new Core page content.
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md	Chinese i18n draft synced to the new Core page content.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+            .WithStopOnFirstError(true)
+            .WithProgress(new Progress<DiffProgress>(p =>
+            {
+                Console.WriteLine($"{p.Completed}/{p.Total}: {p.FileName}");


+- [Upgrade sample](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs)
+- [OSS upgrade sample](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/OSS/OSSUpgradeSample)


+
+Core 主要消费 Dirty 阶段；差分包生成建议交给 `GeneralUpdate.Tools` 或发布流水线完成。标准更新中，下载完成后升级程序会先解压包，再在 `PatchEnabled = true` 时通过 `PatchMiddleware` 调用 `DiffPipeline.DirtyAsync(...)` 应用补丁。


+            .WithStopOnFirstError(true)
+            .WithProgress(new Progress<DiffProgress>(p =>
+            {
+                Console.WriteLine($"{p.Completed}/{p.Total}: {p.FileName}");


+- [Upgrade sample](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs)
+- [OSS upgrade sample](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/OSS/OSSUpgradeSample)


+
+Core mainly consumes the Dirty phase; patch generation should normally be handled by `GeneralUpdate.Tools` or your release pipeline. In standard update, after downloads finish, the updater extracts packages and calls `DiffPipeline.DirtyAsync(...)` through `PatchMiddleware` when `PatchEnabled = true`.


+            .WithStopOnFirstError(true)
+            .WithProgress(new Progress<DiffProgress>(p =>
+            {
+                Console.WriteLine($"{p.Completed}/{p.Total}: {p.FileName}");


+- [Upgrade sample](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs)
+- [OSS upgrade sample](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/OSS/OSSUpgradeSample)


+
+Core 主要消费 Dirty 阶段；差分包生成建议交给 `GeneralUpdate.Tools` 或发布流水线完成。标准更新中，下载完成后升级程序会先解压包，再在 `PatchEnabled = true` 时通过 `PatchMiddleware` 调用 `DiffPipeline.DirtyAsync(...)` 应用补丁。


JusterZhu mentioned this pull request May 31, 2026

Docs subtask: update GeneralUpdate.Core component documentation #47

Closed

JusterZhu mentioned this pull request Jun 1, 2026

docs: final consistency review across all documentation PRs #65

Closed

JusterZhu and others added 10 commits June 3, 2026 15:46

Draft GeneralUpdate.Core documentation

c9da86c

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Expand GeneralUpdate.Core API documentation

d2b3f81

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Document Core manifest support

a72fcd9

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Refine Core manifest bootstrap guidance

b783acd

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Document hook permission script usage

28af4d7

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove driver references from Core docs

1af32d1

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove firmware scope row from Core docs

564c8bc

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Clarify manifest version write-back behavior

4a787a7

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Expand GeneralUpdate Core component docs

9ee9550

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Clarify update precheck event usage

2147892

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

JusterZhu force-pushed the docs/generalupdate-core-draft branch from f6dc5f1 to 2147892 Compare June 3, 2026 07:47

JusterZhu marked this pull request as ready for review June 3, 2026 07:47

Copilot AI review requested due to automatic review settings June 3, 2026 07:47

Copilot started reviewing on behalf of JusterZhu June 3, 2026 07:47 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

JusterZhu merged commit e4fca7a into main Jun 3, 2026
2 checks passed

JusterZhu mentioned this pull request Jun 3, 2026

Docs subtask: final consistency review and documentation validation #55

Closed

JusterZhu mentioned this pull request Jun 3, 2026

Documentation proposal: non-firmware component docs and dual-track cookbooks #45

Closed

JusterZhu deleted the docs/generalupdate-core-draft branch June 3, 2026 16:47

		- [Upgrade sample](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs)
		- [OSS upgrade sample](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/OSS/OSSUpgradeSample)


		Core 主要消费 Dirty 阶段；差分包生成建议交给 `GeneralUpdate.Tools` 或发布流水线完成。标准更新中，下载完成后升级程序会先解压包，再在 `PatchEnabled = true` 时通过 `PatchMiddleware` 调用 `DiffPipeline.DirtyAsync(...)` 应用补丁。


		Core mainly consumes the Dirty phase; patch generation should normally be handled by `GeneralUpdate.Tools` or your release pipeline. In standard update, after downloads finish, the updater extracts packages and calls `DiffPipeline.DirtyAsync(...)` through `PatchMiddleware` when `PatchEnabled = true`.

Uh oh!

Conversation

JusterZhu commented May 31, 2026

Summary

Scope

Related issues

Validation

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

JusterZhu commented May 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants