XHGit · 产品文档

百科、发布与下载

维护项目知识库,管理版本、发布说明及附件。

01

阅读导览

README 适合放项目入口说明,Wiki 适合维护成体系的文档,发布页面则把某个代码版本和用户可下载的附件组织在一起。三者的用途不同,也受各自功能开关和读写权限控制。下载源码压缩包不会自动得到已经编译的软件。

02

为项目建立 Wiki

  1. 进入仓库“Wiki”或“百科”入口;首次使用时,由具有 Wiki 写入权限的成员创建首页。
  2. 用清楚的页面标题组织主题,例如安装、配置、常见问题和开发约定。
  3. 使用 Markdown 编写内容,预览排版与链接,再填写修改说明并保存。
  4. 从首页链接各主题页,避免只有作者知道页面地址。

仓库管理员可以启用内置 Wiki,或配置外部 Wiki 地址。跳转到外部站点时,需要按外部系统编辑;它不会自动变成 XHGit 内置 Wiki 的副本。

03

让文档持续可用

每次软件行为变化时,同时更新相关说明,注明适用版本,避免把旧版本限制写成永久规则。步骤中尽量写出操作目的、输入、预期结果;配置示例使用占位域名与测试值,不要粘贴生产令牌。

文档支持代码块、列表和站内链接。图片或附件受站点上传和访问策略约束,保存后用普通读取者视角核对。具有相关权限的用户也可按页面给出的 Wiki Git 地址使用本地 Git 管理文档,不能把主代码仓库地址误当 Wiki 仓库地址。

04

区分提交、标签和发布

提交保存一次代码变更,标签给某个代码位置命名,发布在标签基础上提供说明和附件。常见命名如 v1.0.0 只是项目约定,平台不会替你判断版本兼容性。

  1. 先确认目标提交已经完成必要审查和测试。
  2. 创建或选择准确的标签,检查标签指向的分支与提交。
  3. 再创建发布,说明新功能、修复、升级步骤和已知问题。

已有受保护标签时,只有满足保护规则的账号可以执行允许的操作,规则配置见仓库管理。

05

创建一次版本发布

  1. 打开仓库“发布”,由具有发布写入权限的成员选择新建发布。
  2. 填写标签、发布标题、说明,并核对目标分支或提交。
  3. 按需要选择草稿或预发布状态。草稿用于整理未公开交付内容,预发布用于提醒用户版本仍在试用阶段。
  4. 上传允许的构建附件并检查名称、版本和平台,再保存或正式发布。

发布说明应给出实际验证过的升级条件。不能只把所有提交标题粘贴进正文,尤其是包含内部路径或敏感问题细节时。

06

向用户提供正确的安装包

附件建议明确标出系统与架构,例如 demo-0.1.0-windows-amd64.zip 和 demo-0.1.0-linux-arm64.tar.gz。Android 应区分测试 APK、可分发 APK 和应用商店需要的包类型,签名由项目自己的构建流程负责。

  1. 从自动构建下载已成功生成的产物,或使用经测试的本地构建结果。
  2. 在独立环境检查可运行性,记录必要的依赖和校验信息。
  3. 把准备长期分发的文件上传到发布附件,核对下载内容再告知用户。

Actions 产物有保留期限,发布附件与工作流日志也不是同一种数据。不要把工作流里短期有效的下载链接当成永久版本地址。

07

下载源码和验证版本

用户可从代码菜单下载 ZIP、TAR.GZ 等当前提供的源码归档,也可从发布页面下载附件。源码归档适合阅读某次快照;继续开发应按Git 指南克隆仓库。

下载前检查仓库拥有者、标签、发布时间、平台架构与附件名称。私有仓库及其附件需要对应访问权限,分享链接不会给匿名用户授权。浏览器提示不存在时,先登录正确账号并从仓库内重新打开。

08

修改、撤回与维护

错误发布由有权限的维护者编辑,说明修正内容;需要删除时认真核对标签与发布的处理范围。删除发布和删除 Git 标签不是同一概念,按页面提示分别判断。仓库归档后相关写入可能被禁用。文档链接失效、附件损坏或版本错配时,在对应议题报告,并附上版本号和可复现信息。