阅读导览
README 适合放项目入口说明,Wiki 适合维护成体系的文档,发布页面则把某个代码版本和用户可下载的附件组织在一起。三者的用途不同,也受各自功能开关和读写权限控制。下载源码压缩包不会自动得到已经编译的软件。
为项目建立 Wiki
- 进入仓库“Wiki”或“百科”入口;首次使用时,由具有 Wiki 写入权限的成员创建首页。
- 用清楚的页面标题组织主题,例如安装、配置、常见问题和开发约定。
- 使用 Markdown 编写内容,预览排版与链接,再填写修改说明并保存。
- 从首页链接各主题页,避免只有作者知道页面地址。
仓库管理员可以启用内置 Wiki,或配置外部 Wiki 地址。跳转到外部站点时,需要按外部系统编辑;它不会自动变成 XHGit 内置 Wiki 的副本。
让文档持续可用
每次软件行为变化时,同时更新相关说明,注明适用版本,避免把旧版本限制写成永久规则。步骤中尽量写出操作目的、输入、预期结果;配置示例使用占位域名与测试值,不要粘贴生产令牌。
文档支持代码块、列表和站内链接。图片或附件受站点上传和访问策略约束,保存后用普通读取者视角核对。具有相关权限的用户也可按页面给出的 Wiki Git 地址使用本地 Git 管理文档,不能把主代码仓库地址误当 Wiki 仓库地址。
区分提交、标签和发布
提交保存一次代码变更,标签给某个代码位置命名,发布在标签基础上提供说明和附件。常见命名如 v1.0.0 只是项目约定,平台不会替你判断版本兼容性。
- 先确认目标提交已经完成必要审查和测试。
- 创建或选择准确的标签,检查标签指向的分支与提交。
- 再创建发布,说明新功能、修复、升级步骤和已知问题。
已有受保护标签时,只有满足保护规则的账号可以执行允许的操作,规则配置见仓库管理。
创建一次版本发布
- 打开仓库“发布”,由具有发布写入权限的成员选择新建发布。
- 填写标签、发布标题、说明,并核对目标分支或提交。
- 按需要选择草稿或预发布状态。草稿用于整理未公开交付内容,预发布用于提醒用户版本仍在试用阶段。
- 上传允许的构建附件并检查名称、版本和平台,再保存或正式发布。
发布说明应给出实际验证过的升级条件。不能只把所有提交标题粘贴进正文,尤其是包含内部路径或敏感问题细节时。
向用户提供正确的安装包
附件建议明确标出系统与架构,例如 demo-0.1.0-windows-amd64.zip 和 demo-0.1.0-linux-arm64.tar.gz。Android 应区分测试 APK、可分发 APK 和应用商店需要的包类型,签名由项目自己的构建流程负责。
- 从自动构建下载已成功生成的产物,或使用经测试的本地构建结果。
- 在独立环境检查可运行性,记录必要的依赖和校验信息。
- 把准备长期分发的文件上传到发布附件,核对下载内容再告知用户。
Actions 产物有保留期限,发布附件与工作流日志也不是同一种数据。不要把工作流里短期有效的下载链接当成永久版本地址。
下载源码和验证版本
用户可从代码菜单下载 ZIP、TAR.GZ 等当前提供的源码归档,也可从发布页面下载附件。源码归档适合阅读某次快照;继续开发应按Git 指南克隆仓库。
下载前检查仓库拥有者、标签、发布时间、平台架构与附件名称。私有仓库及其附件需要对应访问权限,分享链接不会给匿名用户授权。浏览器提示不存在时,先登录正确账号并从仓库内重新打开。
修改、撤回与维护
错误发布由有权限的维护者编辑,说明修正内容;需要删除时认真核对标签与发布的处理范围。删除发布和删除 Git 标签不是同一概念,按页面提示分别判断。仓库归档后相关写入可能被禁用。文档链接失效、附件损坏或版本错配时,在对应议题报告,并附上版本号和可复现信息。