面向初学者的 GitHub
非官方社区技能。标记为 (V) 的内容已与 GitHub 官方文档核对。不构成法律建议。
风格（严格遵守）
- 假定用户一无所知，也不想学习 Git。他们只想要结果。
- 每次给出一步。明确指出他们将要看到的按钮或链接文字。等待用户说完成后再进行下一步。
- 以一句话摘要开头。仅在用户询问时提供细节。
- 如果用户发送截图，请阅读并告知他们当前所处位置，然后再给出下一步指令。
- 如果你（助手）拥有仓库访问权限并且可以自行完成步骤，请主动代劳。通过适当的工具或登录流程请求访问权限。切勿要求用户将密码或访问令牌粘贴到聊天中。
1. 创建仓库
- 点击 github.com 右上角的 +，然后选择“新建仓库”。
- 名称：简短、小写、带连字符（例如
my-plugin）。 - 选择“公开”（任何人可见）或“私有”。
- 勾选“添加 README”。从下拉菜单中选择许可证（参见第 5 节）。
- 点击“创建仓库”。
空仓库会显示一个带有命令行框的“快速设置”页面。初学者可以忽略页面上的所有内容，改用“上传现有文件”链接。
2. 将文件放入仓库（Web 方式，无需 Git）
在仓库页面上：点击“添加文件”，然后选择“上传文件”。接着拖放文件或点击“选择你的文件”。
限制（V：GitHub 文档，向仓库添加文件）：
- 在浏览器中上传时，每个文件最大 25 MiB。
- 每次最多上传 100 个文件。
- 更大的文件（每个最大 100 MiB）需要使用命令行；超过 100 MiB 的文件则需要 Git Large File Storage。
- 受保护分支无法通过 Web 上传进行编辑。
- 推送保护可能会阻止包含已支持机密（例如令牌）的文件。
文件夹：文档说明可以拖放文件或文件夹。如果用户的浏览器无法接受文件夹，可以使用以下方法之一：
- 在 Web 编辑器中创建文件夹：点击“添加文件”、“创建新文件”，在名称框中输入
foldername/filename.md（输入斜杠即可创建文件夹），添加内容，然后提交。请检查当前 UI 中的行为。 - 解压文件夹，分批上传文件以保持其文件夹路径，或使用 GitHub Desktop。
- 如果助手有仓库访问权限，允许其直接推送文件。
Zip 文件将作为单个文件存储；GitHub 不会解压它们。请上传解压后的内容。
最后填写提交消息（简短、说明更改内容），然后点击“提交更改”按钮。
检查结果：打开仓库页面，将文件列表与预期内容进行比较。常见错误：文件落在根目录而不是它们应该在的文件夹中。
3. 带下载的版本（用户应下载的内容）
版本是一个基于 Git 标签的带标记下载页面（V：GitHub 文档，关于版本）。
- 在仓库页面上点击“版本”（右侧），然后选择“起草新版本”。
- 选择一个标签，例如
v1.0.0（输入新标签，然后点击“创建新标签”）。 - 标题和说明：说明是什么、如何安装（三步）、变更内容。
- 将文件拖放到资产框中。适合初学者的版本应包括每个操作系统的构建安装程序或文件、简短手册和安装说明，而不仅仅是裸文件或源代码。
- 点击“发布版本”。
限制（V）：每个文件小于 2 GiB，每个版本最多 1000 个资产，无总大小或带宽限制。
版本说明模板：
- 内容说明（一行）
- 下载：选择你的系统（Windows、macOS、Linux）
- 三步安装指南
- 每个文件的校验和（SHA-256）
- 已知问题
4. 许可证和 README 基础
- 没有许可证的仓库不是开源的；其他人无权重用。请有意识地选择一个。
- MIT：非常宽松，简短。AGPL-3.0 或 GPL：互惠共享。基于 JUCE 开源选项构建的项目受 AGPLv3 约束（V：JUCE 论坛，工作人员），因此在选择前请检查当前的 JUCE 许可证。
- 切勿发布你不拥有版权的供应商文件（手册、出厂预设、徽标、二进制文件）。应链接到它们。
- README 必须回答：这是什么、如何安装、如何使用、许可证、如何报告问题。
5. 避免公开隐私信息（最重要）
在首次公开推送之前，检查每个文件以及提交身份中是否包含：真实姓名、个人电子邮件、电话号码、地址、雇主、令牌、密码、包含用户名的本地路径。
提交身份：
- 使用 GitHub noreply 地址，可在“设置”、“电子邮件”中看到，并勾选“保持我的电子邮件地址私密”。格式：
<数字 ID>+<用户名>@users.noreply.github.com。 - 在提交前设置：
git config user.name "<用户名>"和git config user.email "<ID>+<用户名>@users.noreply.github.com"。推送前使用git log --format='%an <%ae>'进行检查。 - 当助手代表用户提交时，必须使用此身份，切勿使用用户的真实电子邮件。
如果隐私数据已公开（V：GitHub 文档，从仓库中移除敏感数据）：
- 如果是凭据，先撤销或轮换它。这可能就足够了。
- 在本地使用
git-filter-repo重写历史（版本 2.47 或更高版本支持--sensitive-data-removal）。使用--invert-paths --path移除文件，或使用--replace-text替换文本。 - 强制推送以覆盖 GitHub 上的仓库。
- 联系 GitHub 支持以移除缓存视图和拉取请求引用；向他们提供仓库名称、受影响的 PR 数量以及工具输出中的首次更改提交。
- 分叉会保留数据；请分叉所有者移除它。协作者必须变基，而非合并。
- 文档警告：其他人的克隆会保留数据，并且重写可能会暴露已移除的内容。假设数据已被看到。
修复最近一次提交仅适用于分支尖端；旧的提交可能仍然可以通过其直接链接访问，直到 GitHub 清理为止，因此第 4 步仍然适用。
5b. 选择公开的内容
- 研究笔记、捕获的设备数据、个人笔记和聊天记录不属于公开仓库，除非用户明确说明。
- 在公开任何非为公众编写的内容之前，请先询问用户。
6. 日常任务（一次一个）
- 在 Web 上编辑文件：打开文件，点击铅笔图标，修改，提交更改。
- 删除文件：打开文件，点击三个点，选择“删除文件”，提交。
- 重命名或移动：编辑文件名框，输入新路径；提交。
- 将仓库固定到个人资料：个人资料页面，“自定义你的固定项”。
- 启用项目网页（GitHub Pages）：“设置”，“Pages”，选择分支和文件夹。检查当前 UI。
- 报告或跟踪问题：“问题”选项卡。提供用于错误报告的问题模板。
7. 当出现问题时
- 上传被拒绝：检查文件大小（Web 限制 25 MiB）、文件数量（100）以及受保护的分支。
- 缺少文件夹：文件被扁平上传；通过“创建新文件”重新创建路径或重新上传。
- 因机密警告导致推送被拒绝：移除机密、轮换它，然后重试。
- 切勿建议禁用安全提示。
来源
- GitHub 文档，向仓库添加文件：https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository
- GitHub 文档，关于版本：https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
- GitHub 文档，从仓库中移除敏感数据：https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository