docs: write advanced cookbook for production and automation workflows#64
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a comprehensive 10-chapter "Advanced cookbook" guide covering production deployment, CI/CD, version & differential strategies, Bowl reliability, extensions, drivers, security, and failure drills. The document is added as the default-locale Chinese copy under website/docs/quickstart/ and duplicated as zh-Hans and en localized copies under website/i18n/.
Changes:
- New advanced cookbook in default-locale (Chinese) docs.
- Localized
zh-Hanscopy (duplicates the default-locale content). - Localized English copy.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 10 comments.
| File | Description |
|---|---|
| website/docs/quickstart/Advanced cookbook.md | Default-locale (Chinese) advanced cookbook content. |
| website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md | zh-Hans localized copy of the cookbook (duplicates default-locale file). |
| website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md | English localized copy of the cookbook. |
Key concerns:
- All three files link to
./Beginner cookbook.md, which does not exist anywhere in the docs tree — withonBrokenLinks: 'throw'indocusaurus.config.jsthis will break the build. - Several code samples reference APIs that do not exist in this codebase:
ExtensionManager,DriverUpdater,AddBlacklist, andAddListenerDownloadConfig. The real APIs areGeneralExtensionHost, staticGeneralDrivelution,Configinfo.BlackFiles/BlackFormats/SkipDirectorys, andScheme/Tokenfields. - Client-side examples use
GeneralUpdateBootstrapwhereGeneralClientBootstrapis the correct type for client-side flows.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| > **Target audience**: developers who have completed the beginner flow and are integrating GeneralUpdate into production products, CI/CD pipelines, and enterprise release workflows. | ||
|
|
||
| This cookbook complements the [beginner cookbook](./Beginner cookbook.md). The beginner cookbook gets you through your first update loop; this one assumes you've done that and jumps straight into production-grade design. |
| - [GeneralUpdate.Drivelution component docs](../doc/GeneralUpdate.Drivelution.md) | ||
| - [GeneralUpdate.Extension component docs](../doc/GeneralUpdate.Extension.md) | ||
| - [GeneralUpdate.Tools reference](../doc/GeneralUpdate.PacketTool.md) | ||
| - [Beginner cookbook](./Beginner cookbook.md) |
Comment on lines
+480
to
+503
| ```csharp | ||
| var manager = new ExtensionManager(options => | ||
| { | ||
| options.ExtensionsRootPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "extensions"); | ||
| options.TempDownloadPath = Path.Combine(Path.GetTempPath(), "ext_downloads"); | ||
| options.ManifestFileName = "extension.json"; | ||
| }); | ||
|
|
||
| // Query remote available extensions | ||
| var available = await manager.QueryRemoteExtensionsAsync("https://extensions.example.com/api/v1/extensions"); | ||
|
|
||
| // Install | ||
| await manager.InstallAsync("com.mycompany.plugin.search", "1.2.0", | ||
| progress => Console.WriteLine($"Downloading: {progress.Percentage}%")); | ||
|
|
||
| // Update | ||
| await manager.UpdateAsync("com.mycompany.plugin.search", "1.3.0"); | ||
|
|
||
| // Rollback | ||
| await manager.RollbackAsync("com.mycompany.plugin.search", "1.2.0"); | ||
|
|
||
| // Uninstall | ||
| await manager.UninstallAsync("com.mycompany.plugin.search"); | ||
| ``` |
Comment on lines
+546
to
+617
| ```csharp | ||
| var updater = new DriverUpdater(options => | ||
| { | ||
| options.DriverStorePath = @"C:\ProgramData\MyProduct\Drivers"; | ||
| options.TempPath = Path.GetTempPath(); | ||
| options.RequireSignature = true; | ||
| options.BackupBeforeInstall = true; | ||
| }); | ||
|
|
||
| // 1. Validate driver package | ||
| var validation = await updater.ValidatePackageAsync(driverPackagePath); | ||
| if (!validation.IsValid) | ||
| { | ||
| Console.WriteLine($"Driver validation failed: {validation.Errors}"); | ||
| return; | ||
| } | ||
|
|
||
| // 2. Backup current driver | ||
| await updater.BackupCurrentDriverAsync("MyDeviceDriver"); | ||
|
|
||
| // 3. Install new driver | ||
| var result = await updater.InstallAsync(driverPackagePath); | ||
| if (!result.Success) | ||
| { | ||
| // 4. Install failed, auto-rollback | ||
| await updater.RollbackAsync("MyDeviceDriver"); | ||
| Console.WriteLine($"Install failed: {result.ErrorMessage}"); | ||
| return; | ||
| } | ||
|
|
||
| // 5. Verify new driver health | ||
| var health = await updater.HealthCheckAsync("MyDeviceDriver"); | ||
| Console.WriteLine($"Driver health: {health.Status}"); | ||
| ``` | ||
|
|
||
| ### 8.3 Windows driver signing | ||
|
|
||
| Production Windows drivers must be signed: | ||
|
|
||
| 1. Obtain an EV Code Signing certificate | ||
| 2. Pass WHQL (Windows Hardware Quality Labs) certification | ||
| 3. Enable `RequireSignature = true` in `DriverUpdater` | ||
|
|
||
| ### 8.4 Linux driver considerations | ||
|
|
||
| - Use `dkms` (Dynamic Kernel Module Support) for kernel module management | ||
| - Check kernel version compatibility before updating | ||
| - `/lib/modules/$(uname -r)/` typically requires root permissions | ||
| - May need `depmod` and `modprobe` after update | ||
|
|
||
| ### 8.5 Batch / parallel driver updates | ||
|
|
||
| ```csharp | ||
| var updaters = new[] | ||
| { | ||
| new DriverUpdateTask { DeviceId = "PCI\\VEN_8086", PackagePath = @"drivers\gpu_2.1.0.zip" }, | ||
| new DriverUpdateTask { DeviceId = "USB\\VID_0BDA", PackagePath = @"drivers\wifi_1.5.0.zip" }, | ||
| }; | ||
|
|
||
| var results = await Parallel.ForEachAsync(updaters, | ||
| new ParallelOptions { MaxDegreeOfParallelism = 4 }, | ||
| async (task, ct) => | ||
| { | ||
| var updater = new DriverUpdater(/* ... */); | ||
| return await updater.InstallAsync(task.PackagePath); | ||
| }); | ||
|
|
||
| foreach (var r in results) | ||
| { | ||
| Console.WriteLine($"Driver {r.DeviceId}: {(r.Success ? "OK" : "FAILED")}"); | ||
| } | ||
| ``` |
Comment on lines
+323
to
+332
| ```csharp | ||
| new GeneralUpdateBootstrap() | ||
| .AddBlacklist(new List<string> | ||
| { | ||
| "appsettings.json", // user local config | ||
| "logs/", // log directory | ||
| "*.user", // user-specific files | ||
| "cache.db" // local database | ||
| }) | ||
| ``` |
Comment on lines
+640
to
+650
| ```csharp | ||
| // Client-side: add auth header to requests | ||
| new GeneralUpdateBootstrap() | ||
| .AddListenerDownloadConfig(config => | ||
| { | ||
| config.Headers = new Dictionary<string, string> | ||
| { | ||
| ["Authorization"] = $"Bearer {GetAccessToken()}" | ||
| }; | ||
| }); | ||
| ``` |
Comment on lines
+253
to
+266
| ```csharp | ||
| bootstrap.AddListenerUpdatePrecheck(async (precheckArgs) => | ||
| { | ||
| var forcedCount = precheckArgs.Versions.Count(v => v.IsForcibly); | ||
| if (forcedCount > 0) | ||
| { | ||
| // Forced update: don't show a "skip" button | ||
| ShowDialog("A critical security update is required."); | ||
| return false; // false = do not skip, proceed with update | ||
| } | ||
| // Optional update: ask the user | ||
| return await AskUserWhetherToSkip(); | ||
| }); | ||
| ``` |
| | Framework/runtime upgrade | Full | Wide file changes, low diff benefit | | ||
| | Large file update (>100MB) | Differential | Significant size reduction even with many changes | | ||
|
|
||
| ### 5.2 Differential generation and `delete_files.json` |
|
|
||
| > **目标读者**：已有基础使用经验的开发者，正在将 GeneralUpdate 集成到生产产品、CI/CD 流水线和企业级发布工作流中。 | ||
|
|
||
| 本手册与[入门实战手册](./Beginner cookbook.md)互补。入门手册带你跑通第一次更新闭环；本手册假设你已经跑通，直接进入生产级方案设计。 |
|
|
||
| > **目标读者**：已有基础使用经验的开发者，正在将 GeneralUpdate 集成到生产产品、CI/CD 流水线和企业级发布工作流中。 | ||
|
|
||
| 本手册与[入门实战手册](./Beginner cookbook.md)互补。入门手册带你跑通第一次更新闭环；本手册假设你已经跑通，直接进入生产级方案设计。 |
JusterZhu
force-pushed
the
docs/issue-54-advanced-cookbook
branch
2 times, most recently
from
fa46c98 to
f92eb9f
Compare
- Cover production update architecture, standardized Tools artifacts, CI/CD patch generation, version strategy, Differential strategy, Bowl reliability, Extension release workflow, Drivelution workflow, security & compliance, and failure drills. - Provide zh-Hans (default) and English localized copies. - Link to component reference pages and Tools documentation. - Align code snippets and PowerShell examples with current Samples. Closes #54 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Add Semantic Versioning (semver.org) reference in section 4.1 - Map GeneralUpdate 4-part versioning to SemVer MAJOR.MINOR.PATCH - Use language-appropriate URLs: semver.org/lang/zh-CN/ for Chinese, semver.org/ for English - Explain Revision segment as .NET System.Version extension Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
JusterZhu
force-pushed
the
docs/issue-54-advanced-cookbook
branch
from
f92eb9f to
71eff5a
Compare
This was referenced Jun 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #54
Summary
Content
Validation