diff --git a/website/docs/doc/_category_.json b/website/docs/doc/_category_.json index 91f59d3..5af93ba 100644 --- a/website/docs/doc/_category_.json +++ b/website/docs/doc/_category_.json @@ -1,8 +1,8 @@ { - "label": "Doc", - "position": 1, + "label": "Components", + "position": 2, "link": { "type": "generated-index", - "description": "GeneralUpdate开源项目在线文档." + "description": "GeneralUpdate 组件参考文档 — 涵盖 Core、Bowl、Differential、Drivelution 与 Extension 五大非固件组件。" } } diff --git a/website/docs/guide/_category_.json b/website/docs/guide/_category_.json index b5dc17c..a1e16a4 100644 --- a/website/docs/guide/_category_.json +++ b/website/docs/guide/_category_.json @@ -1,8 +1,8 @@ { - "label": "Guide", - "position": 1, + "label": "Guides", + "position": 7, "link": { "type": "generated-index", - "description": "指南." + "description": "平台与运维指南。" } } diff --git a/website/docs/quickstart/Advanced cookbook.md b/website/docs/quickstart/Advanced cookbook.md new file mode 100644 index 0000000..7ad7766 --- /dev/null +++ b/website/docs/quickstart/Advanced cookbook.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 4 +title: 高级实战手册 +--- + +# GeneralUpdate 高级实战手册 + +> **目标读者**：已有基础使用经验的开发者，正在将 GeneralUpdate 集成到生产产品、CI/CD 流水线和企业级发布工作流中。 + +## 内容概览 + +本手册覆盖以下主题： + +1. **生产更新架构设计** — Client、Upgrade、Server、OSS、Tools 与 CI 的整体拓扑 +2. **标准化发布物** — 应用程序包、补丁包、扩展包、OSS 配置的生成与版本管理 +3. **CI/CD 集成** — 在 GitHub Actions / 内部流水线中触发补丁生成 +4. **版本策略** — SemVer、分支发布、渐进式推送、强制更新、多版本顺序升级 +5. **差分策略** — 何时使用差分、删除文件处理、黑名单、大文件场景 +6. **可靠性设计** — Bowl 监控、备份、回滚、启动验证、日志收集 +7. **扩展系统** — Manifest 设计、扩展包发布、兼容性检查、依赖管理 +8. **驱动更新** — Drivelution 权限、签名、平台差异、回滚与重启策略 +9. **安全合规** — Hash 校验、认证下载、OSS 权限、发布审计 +10. **故障演练** — 模拟下载失败、文件锁定、启动崩溃、补丁损坏、权限不足 + +## 章节索引 + +各章节具体内容正在编写中，详见以下子页面： + +> **状态说明**：本文档正在积极构建中。如果你已积累生产实战经验，欢迎通过 Issue 或 PR 贡献案例。 diff --git a/website/docs/quickstart/_category_.json b/website/docs/quickstart/_category_.json index e53d985..7197219 100644 --- a/website/docs/quickstart/_category_.json +++ b/website/docs/quickstart/_category_.json @@ -1,8 +1,8 @@ { - "label": "Quik start", + "label": "Quick Start", "position": 1, "link": { "type": "generated-index", - "description": "Quik start." + "description": "快速入门与实战手册。" } } diff --git a/website/docs/releaselog/_category_.json b/website/docs/releaselog/_category_.json index 6a493ab..59d4fbc 100644 --- a/website/docs/releaselog/_category_.json +++ b/website/docs/releaselog/_category_.json @@ -1,8 +1,8 @@ { - "label": "Release log", - "position": 1, + "label": "Release Log", + "position": 8, "link": { "type": "generated-index", - "description": "发布日志." + "description": "GeneralUpdate 发布日志与版本路线。" } } diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current.json b/website/i18n/en/docusaurus-plugin-content-docs/current.json index 87bde6f..7f15ff4 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/en/docusaurus-plugin-content-docs/current.json @@ -3,36 +3,40 @@ "message": "Next", "description": "The label for version current" }, - "sidebar.tutorialSidebar.category.Doc": { - "message": "Doc", - "description": "The label for category Doc in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Quick Start": { + "message": "Quick Start", + "description": "The label for category Quick Start in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Doc.link.generated-index.description": { - "message": "GeneralUpdate开源项目在线文档.", - "description": "The generated-index page description for category Doc in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Advanced Cookbook": { + "message": "Advanced Cookbook", + "description": "The label for category Advanced Cookbook in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Guide": { - "message": "Guide", - "description": "The label for category Guide in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Components": { + "message": "Components", + "description": "The label for category Components in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Guide.link.generated-index.description": { - "message": "指南.", - "description": "The generated-index page description for category Guide in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Tools": { + "message": "Tools", + "description": "The label for category Tools in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Quik start": { - "message": "Quik start", - "description": "The label for category Quik start in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Infrastructure": { + "message": "Infrastructure", + "description": "The label for category Infrastructure in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Quik start.link.generated-index.description": { - "message": "Quik start.", - "description": "The generated-index page description for category Quik start in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.OSS Update Mode": { + "message": "OSS Update Mode", + "description": "The label for category OSS Update Mode in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Release log": { - "message": "Release log", - "description": "The label for category Release log in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Utilities": { + "message": "Utilities", + "description": "The label for category Utilities in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Release log.link.generated-index.description": { - "message": "发布日志.", - "description": "The generated-index page description for category Release log in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Guides": { + "message": "Guides", + "description": "The label for category Guides in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.Release Log": { + "message": "Release Log", + "description": "The label for category Release Log in sidebar tutorialSidebar" } } diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/_category_.json b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/_category_.json index 1b057b5..753b4ea 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/_category_.json +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/_category_.json @@ -1,8 +1,8 @@ { - "label": "Doc", - "position": 1, + "label": "Components", + "position": 2, "link": { "type": "generated-index", - "description": "GeneralUpdate open source project online documentation." + "description": "GeneralUpdate component reference — covering the five non-firmware components: Core, Bowl, Differential, Drivelution, and Extension." } } diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/_category_.json b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/_category_.json index 0eed47c..9f68035 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/_category_.json +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/_category_.json @@ -1,8 +1,8 @@ { - "label": "Guide", - "position": 1, + "label": "Guides", + "position": 7, "link": { "type": "generated-index", - "description": "Guide." + "description": "Platform and operations guides." } } diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md new file mode 100644 index 0000000..6b536e2 --- /dev/null +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 4 +title: Advanced cookbook +--- + +# GeneralUpdate advanced cookbook + +> **Target audience**: developers who have basic GeneralUpdate experience and are integrating it into production products, CI/CD pipelines, and enterprise release workflows. + +## Overview + +This cookbook covers: + +1. **Production update architecture** — overall topology of Client, Upgrade, Server, OSS, Tools, and CI +2. **Standardized release artifacts** — application packages, patch packages, extension packages, OSS configuration +3. **CI/CD integration** — triggering patch generation in GitHub Actions / internal pipelines +4. **Version strategy** — SemVer, branch releases, staged rollout, forced updates, multi-version sequential upgrades +5. **Differential strategy** — when to use differential, handling deleted files, blacklists, large-file scenarios +6. **Reliability design** — Bowl monitoring, backup, rollback, startup validation, log collection +7. **Extension system** — manifest design, extension package publishing, compatibility, dependency management +8. **Driver updates** — Drivelution permissions, signatures, platform differences, rollback and restart strategy +9. **Security and compliance** — hash validation, authenticated downloads, OSS permissions, release audit +10. **Failure drills** — simulate download failure, file lock, startup crash, corrupted patch, insufficient permissions + +## Chapter index + +Detailed content for each chapter is under active development. See the sub-pages below: + +> **Status**: this document is under active construction. If you have production experience to share, PRs and issues are welcome. diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/_category_.json b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/_category_.json index fcd862a..cc54074 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/_category_.json +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/_category_.json @@ -1,8 +1,8 @@ { - "label": "Quick start", + "label": "Quick Start", "position": 1, "link": { "type": "generated-index", - "description": "Quick start." + "description": "Quick start guides and hands-on cookbooks." } } diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/releaselog/_category_.json b/website/i18n/en/docusaurus-plugin-content-docs/current/releaselog/_category_.json index d65d161..5364196 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/releaselog/_category_.json +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/releaselog/_category_.json @@ -1,8 +1,8 @@ { - "label": "Release log", - "position": 1, + "label": "Release Log", + "position": 8, "link": { "type": "generated-index", - "description": "Release log." + "description": "GeneralUpdate release notes and version roadmap." } } diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json index 87bde6f..01830c6 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json @@ -3,36 +3,40 @@ "message": "Next", "description": "The label for version current" }, - "sidebar.tutorialSidebar.category.Doc": { - "message": "Doc", - "description": "The label for category Doc in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Quick Start": { + "message": "快速入门", + "description": "The label for category Quick Start in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Doc.link.generated-index.description": { - "message": "GeneralUpdate开源项目在线文档.", - "description": "The generated-index page description for category Doc in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Advanced Cookbook": { + "message": "高级实战手册", + "description": "The label for category Advanced Cookbook in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Guide": { - "message": "Guide", - "description": "The label for category Guide in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Components": { + "message": "组件文档", + "description": "The label for category Components in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Guide.link.generated-index.description": { - "message": "指南.", - "description": "The generated-index page description for category Guide in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Tools": { + "message": "工具", + "description": "The label for category Tools in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Quik start": { - "message": "Quik start", - "description": "The label for category Quik start in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Infrastructure": { + "message": "基础设施", + "description": "The label for category Infrastructure in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Quik start.link.generated-index.description": { - "message": "Quik start.", - "description": "The generated-index page description for category Quik start in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.OSS Update Mode": { + "message": "OSS 更新模式", + "description": "The label for category OSS Update Mode in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Release log": { - "message": "Release log", - "description": "The label for category Release log in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Utilities": { + "message": "工具类", + "description": "The label for category Utilities in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Release log.link.generated-index.description": { - "message": "发布日志.", - "description": "The generated-index page description for category Release log in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Guides": { + "message": "指南", + "description": "The label for category Guides in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.Release Log": { + "message": "发布日志", + "description": "The label for category Release Log in sidebar tutorialSidebar" } } diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/_category_.json b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/_category_.json index 91f59d3..3668128 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/_category_.json +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/_category_.json @@ -1,8 +1,8 @@ { - "label": "Doc", - "position": 1, + "label": "组件文档", + "position": 2, "link": { "type": "generated-index", - "description": "GeneralUpdate开源项目在线文档." + "description": "GeneralUpdate 组件参考文档 — 涵盖 Core、Bowl、Differential、Drivelution 与 Extension 五大非固件组件。" } } diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/_category_.json b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/_category_.json index b5dc17c..7611c29 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/_category_.json +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/_category_.json @@ -1,8 +1,8 @@ { - "label": "Guide", - "position": 1, + "label": "指南", + "position": 7, "link": { "type": "generated-index", - "description": "指南." + "description": "平台与运维指南。" } } diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md new file mode 100644 index 0000000..7ad7766 --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 4 +title: 高级实战手册 +--- + +# GeneralUpdate 高级实战手册 + +> **目标读者**：已有基础使用经验的开发者，正在将 GeneralUpdate 集成到生产产品、CI/CD 流水线和企业级发布工作流中。 + +## 内容概览 + +本手册覆盖以下主题： + +1. **生产更新架构设计** — Client、Upgrade、Server、OSS、Tools 与 CI 的整体拓扑 +2. **标准化发布物** — 应用程序包、补丁包、扩展包、OSS 配置的生成与版本管理 +3. **CI/CD 集成** — 在 GitHub Actions / 内部流水线中触发补丁生成 +4. **版本策略** — SemVer、分支发布、渐进式推送、强制更新、多版本顺序升级 +5. **差分策略** — 何时使用差分、删除文件处理、黑名单、大文件场景 +6. **可靠性设计** — Bowl 监控、备份、回滚、启动验证、日志收集 +7. **扩展系统** — Manifest 设计、扩展包发布、兼容性检查、依赖管理 +8. **驱动更新** — Drivelution 权限、签名、平台差异、回滚与重启策略 +9. **安全合规** — Hash 校验、认证下载、OSS 权限、发布审计 +10. **故障演练** — 模拟下载失败、文件锁定、启动崩溃、补丁损坏、权限不足 + +## 章节索引 + +各章节具体内容正在编写中，详见以下子页面： + +> **状态说明**：本文档正在积极构建中。如果你已积累生产实战经验，欢迎通过 Issue 或 PR 贡献案例。 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/_category_.json b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/_category_.json index e53d985..67b2184 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/_category_.json +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/_category_.json @@ -1,8 +1,8 @@ { - "label": "Quik start", + "label": "快速入门", "position": 1, "link": { "type": "generated-index", - "description": "Quik start." + "description": "快速入门与实战手册。" } } diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/releaselog/_category_.json b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/releaselog/_category_.json index 6a493ab..f665e01 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/releaselog/_category_.json +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/releaselog/_category_.json @@ -1,8 +1,8 @@ { - "label": "Release log", - "position": 1, + "label": "发布日志", + "position": 8, "link": { "type": "generated-index", - "description": "发布日志." + "description": "GeneralUpdate 发布日志与版本路线。" } } diff --git a/website/sidebars.js b/website/sidebars.js index f6a3519..94df74a 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -1,22 +1,120 @@ /** - * Creating a sidebar enables you to: - - create an ordered group of docs - - render a sidebar for each doc of that group - - provide next/previous navigation - - The sidebars can be generated from the filesystem, or explicitly defined here. - - Create as many sidebars as you want. + * @ts-check + * + * GeneralUpdate documentation sidebar. + * + * Pages are grouped by role: + * 1. Quick Start & Cookbooks — first-time user flow and advanced production guides + * 2. Components — non-firmware component reference (Core, Bowl, + * Differential, Drivelution, Extension) + * 3. Tools — GeneralUpdate.Tools usage and artifact reference + * 4. Infrastructure — server-side services (Spacestation, Hub) + * 5. OSS Update Mode — OSS-based update flows (.NET & MAUI) + * 6. Utilities — shared helpers (GeneralTracer) + * 7. Guides — operational / platform-specific guides + * 8. Release Log — changelog and roadmap */ -// @ts-check - /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { - // By default, Docusaurus generates a sidebar from the docs folder structure - tutorialSidebar: - [ - { type: 'autogenerated', dirName: '.'} + tutorialSidebar: [ + // ── 1. Quick Start & Cookbooks ────────────────────────────────── + { + type: 'category', + label: 'Quick Start', + collapsed: false, + items: [ + 'quickstart/Quik start', + 'quickstart/Sample UI', + 'quickstart/Beginner cookbook', + ], + }, + { + type: 'category', + label: 'Advanced Cookbook', + collapsed: true, + items: [ + 'quickstart/Advanced cookbook', + ], + }, + + // ── 2. Components (non-firmware) ──────────────────────────────── + { + type: 'category', + label: 'Components', + collapsed: false, + items: [ + 'doc/Component Introduction', + 'doc/GeneralUpdate.Core', + 'doc/GeneralUpdate.Bowl', + 'doc/GeneralUpdate.Differential', + 'doc/GeneralUpdate.Drivelution', + 'doc/GeneralUpdate.Extension', + 'doc/Android auto-update', + ], + }, + + // ── 3. GeneralUpdate.Tools ────────────────────────────────────── + { + type: 'category', + label: 'Tools', + collapsed: true, + items: [ + 'doc/GeneralUpdate.PacketTool', + ], + }, + + // ── 4. Infrastructure ─────────────────────────────────────────── + { + type: 'category', + label: 'Infrastructure', + collapsed: true, + items: [ + 'doc/GeneralSpacestation', + 'doc/UpgradeHub', + ], + }, + + // ── 5. OSS Update Mode ────────────────────────────────────────── + { + type: 'category', + label: 'OSS Update Mode', + collapsed: true, + items: [ + 'doc/GeneralClient.OSS', + 'doc/GeneralUpdate.Maui.OSS', + ], + }, + + // ── 6. Utilities ──────────────────────────────────────────────── + { + type: 'category', + label: 'Utilities', + collapsed: true, + items: [ + 'doc/GeneralTracer', + ], + }, + + // ── 7. Guides ─────────────────────────────────────────────────── + { + type: 'category', + label: 'Guides', + collapsed: true, + items: [ + { type: 'autogenerated', dirName: 'guide' }, + ], + }, + + // ── 8. Release Log ────────────────────────────────────────────── + { + type: 'category', + label: 'Release Log', + collapsed: true, + items: [ + 'releaselog/GeneralUpdateReleaselog', + ], + }, ], };