仓库创建与开源许可证

在GitHub上，一切项目都始于一个仓库(Repository, Repo)。你可以把它想象成一个项目的专属文件夹，里面存放代码、文档、图片等所有相关文件，并且Git会记录这个文件夹里所有内容的历史变化。

仓库 (Repository)

  • GitHub上项目存储的基本单位。
  • 包含项目的所有文件、修订历史（提交记录）、分支、议题(Issues)、拉取请求(Pull Requests)等。
  • 创建时有两个关键选项：公开(Public) 或 私有(Private)。

创建仓库的步骤（在网站上）：

image

image

  • 点击右上角 + 图标 -> New repository。
  • 填写仓库名称 (Repository name)、描述 (Description)。
  • 选择公开/私有。
    最后初始化选项：
  • Add a README file：强烈建议勾选。README是项目的说明书，用Markdown编写，用于介绍项目。
  • Add .gitignore：可选。.gitignore文件用于告诉Git哪些文件或文件夹不需要纳入版本管理（如编译产物、日志、IDE配置文件）。
  • Choose a license：核心决策点

开源许可证 (Open Source License)：一份法律文件，明确规定了他人如何使用、修改和分发你的代码。

为什么重要？ 没有许可证的代码，默认是“保留所有权利”，他人无法合法地使用或贡献。选择一个合适的许可证是开源项目的法律保障。

image

公开仓库 ≠ 自动开源：一个仓库设为公开，只意味着别人能看到你的代码。只有附带了明确的开源许可证，它才算是一个真正的“开源项目”，别人才有法律依据去使用、分发和修改。

.gitignore的作用：它不是“删除”文件，而是“忽略”文件。被忽略的文件不会进入Git的版本跟踪，但依然会存在于你的本地文件夹中。这避免了将临时文件、敏感信息（如密码配置文件）误提交到仓库。

提交(Commit)

创建仓库后，你需要开始往里面添加或修改内容。每一次有意义的修改，都应该被记录为一个提交 (Commit)。

提交 (Commit)

  • Git版本控制中的基本单位，代表项目在某个时间点的完整快照。

  • 每个提交都有一个唯一的哈希值 (Hash, 如 a1b2c3d)，用于标识。

  • 提交必须包含变更内容和提交信息，变更内容是具体修改了哪些文件。提交信息 (Commit Message)则是对本次修改的简短描述。好的提交信息至关重要。

在网站上创建提交的流程：

在仓库页面，点击文件列表上方的 Add file -> Create new file 或 Upload files。

编辑或上传文件后，滚动到页面底部的 “Commit changes” 区域。

填写提交信息。通常分为两行：

  • 第一行（标题）：简短总结，不超过50字。例如：“修复用户登录验证逻辑”。

  • 第二行（正文）：可选，详细说明修改的原因、背景或影响。例如：“修复了当用户密码包含特殊字符时，正则表达式匹配失败的问题。”

  • 选择提交方式：直接提交到主分支，或创建新分支并启动拉取请求。

提交信息“敷衍了事”：写“更新”或“fix bug”这样的信息是无效的。几个月后，你或你的队友将完全无法理解这个提交的目的。强制要求自己写清晰、有意义的提交信息，这是优秀开发者的基本素养。
提交粒度：一次提交应该只完成一个逻辑上独立的修改。不要把“修复BugA”和“添加新功能B”混在一个提交里。这有利于代码审查和问题回溯。

分支(Branch)与拉取请求(Pull Request/PR)

直接在项目的主分支（通常是 main 或 master）上修改是危险的，可能会破坏稳定版本。分支 (Branch) 就是为了解决这个问题。

分支 (Branch)

  • 从某个提交点“岔开”的一条独立开发线。
  • 你可以在分支上自由地实验、开发新功能或修复Bug，而不会影响主分支的稳定性。
  • 默认分支通常是 main。

在网站上使用分支

创建分支：在仓库页面，点击分支下拉框（显示 main 的地方），输入新分支名（如 feature/add-search），点击 Create branch。

在新分支上工作：现在你的所有修改（C5的提交）都会发生在这个新分支上。

发起拉取请求：当功能开发完成并测试后，你需要将分支的修改合并回 main 分支。这个合并请求就是拉取请求。

拉取请求 (Pull Request, PR)：一个请求，请求将某个分支的更改合并到另一个分支（通常是 main）。

PR的核心价值远不止“合并代码”。

  • 代码审查 (Code Review)：团队成员可以在PR中讨论代码，提出修改意见。
  • 持续集成 (CI)：可以配置自动化测试，在合并前验证代码。
  • 历史记录：PR记录了为什么做这个修改、讨论了什么、谁批准的，是宝贵的项目日志。

创建PR的步骤：

在仓库页面，GitHub通常会在你推送新分支后自动提示 Compare & pull request。

点击进入PR创建页面。

填写PR标题和描述，清晰说明这个PR要做什么、为什么。

指定基础分支 (base, 如 main) 和比较分支 (compare, 如你的功能分支)。

可以指定审查者 (Reviewers)。

点击 Create pull request。之后，可以在PR中进行讨论，审查通过后，由有权限的人点击 Merge pull request 完成合并。

image

README文档

一个专业的项目，不仅要有好的代码，还要有好的文档和展示。这在GitHub上主要通过 README文件 和 个人/组织主页 来实现，而它们的编辑都依赖于 Markdown 语法。

Markdown

  • 一种轻量级标记语言，用简单的符号（如 # 表示标题， * 表示列表）就能生成格式清晰的HTML文档。
  • 为什么是GitHub的通用语？ 因为它易读易写，且能被GitHub完美渲染。README、议题、PR描述、Wiki都使用Markdown。

README.md 文件：仓库根目录下的 README.md 文件是项目的第一印象和使用手册。

一个好的README应包含：

  • 项目名称和简短描述。
  • 安装和快速上手指南。
  • 使用方法示例。
  • 如何贡献代码。
  • 许可证信息。

个人主页说明

创建一个与你用户名同名的仓库（如你的账号是 octocat，则创建 octocat/octocat）。

这个仓库的 README.md 内容将直接显示在你的GitHub个人主页顶部，成为你的“数字名片”。

忽略README：一个空荡荡或内容简陋的仓库会大大降低项目的吸引力。花时间写一个清晰的README是对潜在用户和贡献者的基本尊重。
Markdown语法不统一：虽然Markdown简单，但不同的渲染器可能对某些语法支持不同。尽量使用GitHub Flavored Markdown (GFM) 的标准语法，以确保在GitHub上显示一致。