Skip to main content

· 5 min read
Kyle

Git 与 AtomGit 实践:维护者审核与合并变更请求

本教程旨在指导维护者如何有效地审核和合并变更请求,以确保项目的质量和一致性。

1. 审核Change Request

维护者收到Change Request后,应执行以下步骤:

  1. 查看变更内容

  2. 提出反馈或建议

    • 如果发现问题或有改进建议,可以在Change Request页面留言,要求贡献者进行相应修改。
  3. 确认无误后批准

    • 如果变更符合要求,点击"通过"/“不通过”按钮,确认Change Request。

2. 合并Change Request

审核通过后,维护者可以将贡献者的变更合并到上游仓库:

  1. 点击"合并"按钮

    • 在Change Request页面,点击页面右上角的"合并"按钮。
  2. 选择合并方式

    • 通常选择"创建合并提交"方式进行合并,确保所有变更记录完整保留。
  3. 确认合并信息

    • 检查合并信息无误后,点击确认完成操作。

3. 同步上游仓库更新

所有贡献者应定期同步上游仓库的最新更改,以保持与自己fork的仓库的同步。在终端/PowerShell中执行以下步骤: 以下内容是在你电脑的 my_open_source_contributions 仓库目录下执行。

  1. 添加上游仓库

    git remote add upstream git@atomgit.com:atomgit_operate/my_open_source_contributions.git
  2. 获取上游仓库的更新

    git fetch upstream/master
  3. 切换到主分支并合并

    git checkout master
    git merge upstream/master
  4. 推送更新到Fork仓库

    git push origin master
  5. 再次提交变更请求

    • 重复提交变更请求的步骤,确保所有更改都被正确记录和审核。

4. 最佳实践

  • 定期同步:保持本地仓库与上游仓库的同步,减少冲突发生。
  • 详细提交信息:每次提交都应有清晰、详细的说明,便于他人理解更改内容。
  • 内容审核:维护者应进行严格的内容审核,确保提交的质量。
  • 选择审核人:提交Change Request时,选择审核人(reviewers)来审核您的变更。
  • 书写清晰的PR描述:在提交Change Request时,提供详细的描述,说明更改的原因和内容,便于审核人员理解。

通过遵循这些步骤和最佳实践,维护者可以有效地管理和合并变更请求,确保项目的持续健康发展。

推荐阅读

如果你对本文内容感兴趣,或者希望了解更多相关知识,以下是一些推荐阅读的文章:

  1. Git 与 AtomGit 实践:从零到一,单用户操作单仓库

    • 详细介绍了如何从零开始使用 Git 和 AtomGit 进行单用户操作单仓库的完整流程,包括环境配置、创建仓库、提交更改等步骤。
  2. Git 与 AtomGit 实践:向上游仓库贡献内容

    • 详细介绍了如何向上游仓库贡献内容的完整流程,包括Fork、克隆、提交更改和提交变更请求等步骤。

通过阅读这些文章,你将能够更全面地了解如何使用 Git 和 AtomGit 进行开源项目的贡献和管理。希望这些资源对你有所帮助!

· 10 min read
Kyle

Git 与 AtomGit 实践:从零到一,单用户操作单仓库

本教程适用于 Windows、macOS 和 Linux 平台。

此任务主要是帮助用户在 AtomGit 上从零开始创建并管理一个单一仓库,涵盖单用户操作单仓库的最常用操作流程。

1、注册或登录 AtomGit

网址 https://atomgit.com

2、验证手机号码和邮箱的正确性

在 AtomGit 上产生内容前,需先验证手机号码和邮箱的正确性。如果没有验证过,在AtomGit网站上会有弹出提醒,如果没有弹出提醒,请按照以下步骤进行验证:

  • 点击AtomGit网站界面右上角的头像
  • 进入“个人中心”
  • 选择“基本信息”
  • 进入“帐号绑定”
  • 检查验证状态或修改手机号和邮箱

3、创建仓库

1)点击“+”按钮

  • 在 AtomGit 界面的右上角,点击“+”按钮。

2)新建代码库

  • 选择“新建代码库”。

3)填写代码库详细信息

  • 代码库名称:支持中英文。
  • 归属:默认是当前登录的账户。
  • 路径:只能包含字母、数字、''、'.'和'-',且必须以字母、数字或''开头。
  • 关联社区:(可选)。
  • 公开性:根据实际情况设置,本次练习作业需设置为公开。
  • 代码库描述:自行输入描述内容。
  • 创建README.md:系统会自动创建一个Markdown文件。
  • 创建 .gitignore:此选项为可选。
  • 添加开源许可证:根据实际情况选择一个,非常重要。

4)确认创建

  • 点击“确定”以完成代码库的创建。

4、Git 环境准备

1)检查Git环境

Windows:

  • 按下 Win 键打开开始菜单。
  • 输入 PowerShell
  • 在搜索结果中,右键点击 Windows PowerShell,选择 以管理员身份运行
  • 在弹出的提示中点击

MacOS:

  • 打开 终端(Terminal)应用。
  • 可以通过 Spotlight(按下 Command + 空格)搜索 "Terminal" 来打开。

Linux:

  • 打开终端(Terminal)。
  • 在大多数发行版中,可以使用快捷键 Ctrl + Alt + T 打开终端。

在终端/PowerShell 中输入以下命令并回车:

git --version

结果判断

  • 如果显示 Git 版本号(如 git version 2.x.x),表示 Git 已正确安装。
  • 如果出现错误信息,表示 Git 未安装。

2)安装Git

Windows:

  • 如果Git未安装,打开浏览器访问以下链接下载Git安装包: 下载Git-2.47.1-64-bit.exe
  • 下载完成后,解压并双击运行安装包。
  • 在安装向导中,依次点击 Next
  • Select Components 界面,确保所有选项均已勾选,以便后续操作更方便。
  • 继续点击 Next 直至安装完成。
  • 安装完成后,重新执行 检查Git环境 步骤以确认安装成功。

MacOS:

  • MacOS 通常预装了 Git。如需安装或更新,可以:
    • 通过 Homebrew 安装:brew install git
    • 或下载 Git 安装包:访问 Git 官网

Linux:

  • 大多数 Linux 发行版预装了 Git。如需安装,可以使用包管理器:
    • Ubuntu/Debian:sudo apt-get install git
    • Fedora:sudo dnf install git
    • CentOS:sudo yum install git

3)配置Git

  • 打开终端(Windows 用户使用 PowerShell)。
  • 执行以下命令生成SSH密钥:
    ssh-keygen -t rsa -C "your_email@example.com"
  • 按提示一路 Enter 键,使用默认设置生成SSH Key。
  • 复制SSH公钥:
    • 生成的SSH Key文件路径:
      • Windows:C:\Users\你的用户名\.ssh\id_rsa.pubC:\Users\你的用户名\.ssh\id_随机码.pub
      • MacOS/Linux:~/.ssh/id_rsa.pub
    • 使用以下命令查看公钥内容:
      • Windows:cat C:\Users\你的用户名\.ssh\id_rsa.pubcat C:\Users\你的用户名\.ssh\id_随机码.pub
      • MacOS/Linux:cat ~/.ssh/id_rsa.pub
    • 复制查看显示出来的公钥内容,后续将在AtomGit网站上使用。

4)在AtomGit网站上配置SSH Key

  • 在AtomGit网站上点击右上角头像->个人中心->安全中心SSH Keys->添加 SSH 公钥->将刚才复制的SSH Key粘贴到“公钥”文本框中->点击“确定”。

5)测试SSH Key是否生效

Windows/Linux/MacOS:

  • 在终端/PowerShell中输入下面命令并回车,如果看到"successfully",表明SSH Key配置成功。
    ssh -T git@atomgit.com

6)配置Git用户名和邮箱

Windows/Linux/MacOS:

  • 在终端/PowerShell中分别输入下面每行命令并回车,其中name和email的内容可以随便写,但是推荐和您的AtomGit账户名和邮箱一致。
    git config --global user.name "你的名字"
    git config --global user.email "你的邮箱"

5、本地操作仓库

1)获取仓库的 Git 地址

  • 在第三步创建的仓库页面,点击右上角的"克隆/下载"按钮。
  • 确保选择了"SSH"选项。
  • 页面会显示类似"git@atomgit.com:username/repository"格式的地址(注意:不要直接复制这里的示例,要使用你在 AtomGit 网站上看到的实际地址,其中 username 是你的 AtomGit 用户名,repository 是你的仓库名称)。
  • 点击地址右侧的复制按钮复制你的仓库 SSH 地址。

2)将仓库克隆到电脑本地

Windows:

  • 在 PowerShell 中执行(使用你从 AtomGit 网站上复制的实际仓库地址):
    git clone <在AtomGit网站上复制的仓库地址>

MacOS/Linux:

  • 在终端中执行(使用你从 AtomGit 网站上复制的实际仓库地址):
    git clone <在AtomGit网站上复制的仓库地址>

3)进入仓库目录

Windows:

  • 在 PowerShell 中执行(使用你的实际仓库名称):
    cd <你的仓库名称>

MacOS/Linux:

  • 在终端中执行(使用你的实际仓库名称):
    cd <你的仓库名称>

4)打开目录并在里添加文件或者更新文件

Windows:

  • 在 PowerShell 中执行:
    start .

MacOS/Linux:

  • 请使用合适的编辑器操作目录的内容。

对于所有平台:

 - 此时你可以在当前目录下:
- 添加新的文件或子文件夹
- 删除已有的文件或子文件夹
- 修改已有文件的内容
- 重命名文件或子文件夹

例如:
- 添加一个新文件test.txt,写入"hello world"
- 创建一个新的子文件夹docs
- 修改README.md文件的内容
- 删除不需要的文件

5)提交文件

Windows/Linux/MacOS:

  • 在终端/PowerShell中执行以下命令提交文件:
    git add .
    git commit -m "在这里写一句你喜欢的或者能表达本次更新内容的提交注释"
    git push

6)查看更新结果

  • 现在你可以访问 AtomGit 网站查看你的仓库更新了。

至此,你已经成功迈出了使用 Git 的第一步。随着不断练习,你会发现 Git 是一个非常强大且有趣的工具。期待看到你在 AtomGit 上创造出更多精彩的项目!

推荐阅读

如果你对本文内容感兴趣,或者希望了解更多相关知识,以下是一些推荐阅读的文章:

  1. Git 与 AtomGit 实践:向上游仓库贡献内容

    • 详细介绍了如何向上游仓库贡献内容的完整流程,包括Fork、克隆、提交更改和提交变更请求等步骤。
  2. Git 与 AtomGit 实践:维护者审核与合并变更请求

    • 介绍了维护者如何审核和合并变更请求的流程,确保项目的质量和一致性。

通过阅读这些文章,你将能够更全面地了解如何使用 Git 和 AtomGit 进行开源项目的贡献和管理。希望这些资源对你有所帮助!

· 8 min read
Kyle

Git 与 AtomGit 实践:向上游仓库贡献内容

主要介绍了如何向上游仓库或其他开源项目贡献内容,以参与开源社区建设。

我们将以 my_open_source_contributions 作为上游仓库,如何向此仓库贡献内容为例,介绍如何参与开源项目。

1、账号准备与环境检查

提示:为确保顺利完成本练习,在操作前请先完整阅读 《Git 与 AtomGit 实践:从零到一,单用户操作单仓库》,熟悉基本概念和操作后再继续。

1)注册 AtomGit 账号

2)验证手机号和邮箱

3)Git 环境配置

2. Fork(分叉/复制)上游仓库

贡献者在开始贡献前,需要先将上游仓库Fork到自己的AtomGit账号下:

  1. 打开您的浏览器,访问上游仓库页面:https://atomgit.com/atomgit_operate/my_open_source_contributions
  2. 在仓库页面的右上角,点击"Fork"按钮,将仓库Fork到您的账户中。

3. 克隆Fork后的仓库

在本地机器上,请按照您的操作系统选择相应步骤操作,请将您的用户名替换为您的AtomGit用户名。

Windows 用户:

  1. 打开PowerShell

    • 点击"开始"菜单,输入"PowerShell"
    • 点击"Windows PowerShell"以打开它
  2. 执行克隆命令

    • 在PowerShell窗口中,输入以下命令并按回车执行:
      git clone git@atomgit.com:您的用户名/my_open_source_contributions.git
  3. 进入仓库目录

    cd my_open_source_contributions
  4. 打开项目目录

    start .

macOS 用户:

  1. 打开终端

    • 使用 Spotlight(Command + 空格)搜索"Terminal"
    • 点击"Terminal"应用打开
  2. 执行克隆命令

    git clone git@atomgit.com:您的用户名/my_open_source_contributions.git
  3. 进入仓库目录

    cd my_open_source_contributions
  4. 打开项目目录

    open .

Linux 用户:

  1. 打开终端

    • 使用快捷键 Ctrl + Alt + T
    • 或从应用程序菜单中打开终端
  2. 执行克隆命令

    git clone git@atomgit.com:您的用户名/my_open_source_contributions.git
  3. 进入仓库目录

    cd my_open_source_contributions
  4. 打开项目目录

    • 使用您的习惯编辑器或文件管理器打开当前目录:

4. 增删改文件并提交更改

  1. 创建和编辑文件

    • 在项目目录中,使用任意文本编辑器(如VS Code、Sublime Text、记事本等)
    • 创建一个新文件,您可以自由选择文件名和类型,例如:
      • my_story.txt
      • project_ideas.md
      • notes.py
      • config.json
      • data.yaml
    • 在新文件中添加任意内容,比如:
      这是我开源贡献的历程
      让我们一起开源贡献
    • 编辑完成后保存更改
  2. 提交更改

5. 推送到Fork仓库

将本地的更改推送到自己Fork的仓库:

在终端/PowerShell中执行:

git push origin master

6. 提交变更请求(Change Request)

  1. 登录AtomGit

    • 打开您的浏览器,访问AtomGit并登录您的账户。
  2. 导航至Fork的仓库

  3. 提交Change Request

    • 点击仓库页面左侧菜单中的"变更请求"菜单。在"新建变更请求"页面,确保"来源"选择为您的账户下的Fork仓库的master分支。默认已经正确选择。目的分支选择为"上游仓库的master分支"。
    • 填写Change Request的标题和描述,确保清晰说明所做的更改。例如:
      • 标题:添加新功能和开源寄语
      • 描述:本次提交包括添加“xxx”文件以及在main.txt中添加我的开源寄语,旨在丰富项目内容并表达对开源的支持。
      • 审核人:选择审核人(reviewers)来审核您的变更。
  4. 提交并等待审核

    • 点击"确定"按钮,完成变更请求的创建,等待维护者的审核。

注意:作为贡献者角色,到此完成了向上游仓库贡献内容。

7. 最佳实践

  • 定期同步:保持本地仓库与上游仓库的同步,减少冲突发生。
  • 详细提交信息:每次提交都应有清晰、详细的说明,便于他人理解更改内容。
  • 内容审核:维护者应进行严格的内容审核,确保提交的质量。
  • 选择审核人:提交Change Request时,选择审核人(reviewers)来审核您的变更。
  • 书写清晰的Change Request描述:在提交Change Request时,提供详细的描述,说明更改的原因和内容,便于审核人员理解。

推荐阅读

如果你对本文内容感兴趣,或者希望了解更多相关知识,以下是一些推荐阅读的文章:

  1. Git 与 AtomGit 实践:从零到一,单用户操作单仓库

    • 详细介绍了如何从零开始使用 Git 和 AtomGit 进行单用户操作单仓库的完整流程,包括环境配置、创建仓库、提交更改等步骤。
  2. Git 与 AtomGit 实践:维护者审核与合并变更请求

    • 介绍了维护者如何审核和合并变更请求的流程,确保项目的质量和一致性。

通过阅读这些文章,你将能够更全面地了解如何使用 Git 和 AtomGit 进行开源项目的贡献和管理。希望这些资源对你有所帮助!

· 20 min read
Kyle
Hex

Git 与 AtomGit 实践:团队工作流程的探讨与实践

本教程适用于所有使用 Git 进行团队协作的开发团队。

在软件开发中,选择合适的工作流对于提高团队效率和代码质量至关重要。本文将首先深入探讨团队工作流的理论基础,然后通过一个完整的项目实践示例,展示如何在 AtomGit 上应用这套工作流。

理论篇:工作流设计

1、分支策略

在我们的工作流中,主要维护两个长期分支:

  • master: 生产环境分支,始终保持代码的稳定性和可部署状态。
  • testing: 测试环境分支,用于集成和验证待测试的功能。

分支策略设计考虑

  1. 为何不使用传统的 master/production 分支?

    • 单一测试环境限制:由于团队只有一个办公网测试环境,直接提测多个 feature 分支可能导致混乱和冲突。
    • 简化分支管理:通过设立 testing 分支作为统一的测试入口,简化了分支流转和管理的复杂度。
  2. 分支权限控制

    • master 分支:仅允许通过合并请求(Merge Request, MR)进行代码合并,确保代码的稳定性和审查的彻底性。
    • testing 分支:允许开发人员直接推送代码,便于快速集成和测试。
    • 临时分支:如 feature 分支或 hotfix 分支,由创建者拥有完全权限,便于独立开发和管理。

2、开发场景与分支流转

在日常开发中,我们主要面临以下几种情形:

  1. 新功能开发
  2. 线上 BUG 修复
  3. 运营文案修改

每种情形有其特定的分支流转流程,确保开发的有序性和代码的稳定性。

2.1 新功能开发

完整流程:

  1. master 创建 feature 分支
    • 例如:feature/playlist
  2. 在 feature 分支上进行开发
    • 完成功能开发后进行本地测试
  3. 提交第一个 MR 到 testing 分支
    • 必须进行 Code Review
    • 解决 Review 意见
    • 合并到 testing 环境进行全面测试
  4. 测试过程中发现问题
    • 继续在 feature 分支上修复问题
    • 提交新的 commit 并更新 MR
  5. 测试通过后提交新的 MR 到 master
    • 再次进行 Code Review
    • 确认无误后合并到 master
  6. 合并后操作
    • 打 tag 发布代码
    • 删除 feature 分支,保持分支整洁

2.2 线上 BUG 修复

根据 BUG 的紧急程度,分为两种修复路径:

  1. 紧急修复流程

    • master 创建 hotfix 分支,例如:hotfix/player-crash
    • 完成修复后直接提交 MR 到 master
    • 经过 Code Review 后紧急合并上线
    • 另外提交 MR 到 testing 分支,同步修复
    • 删除 hotfix 分支,避免分支膨胀
  2. 常规修复流程

    • master 创建 hotfix 分支,例如:hotfix/ui-glitch
    • 完成修复后先提交 MR 到 testing 分支
    • testing 环境中进行测试验证
    • 测试通过后再提交 MR 到 master 分支
    • 合并发布后删除 hotfix 分支

2.3 运营文案修改

文案修改流程与 BUG 修复类似,但主要侧重于内容的准确性和时效性:

  1. master 创建文案分支
    • 例如:content/welcome-text-update
  2. 在文案分支上进行修改
    • 确保修改前后内容对比清晰
  3. 提交 MR 到 testing 分支
    • 进行文案验证和多轮校对
  4. 验证通过后提交 MR 到 master
    • 经过 Code Review 后合并发布
  5. 合并后操作
    • 删除文案分支,保持分支整洁

3、MR 管理规范

3.1 MR 提交规范

  1. 标题格式

    • 功能:[Feature] Add playlist function
    • 修复:[Fix] Resolve player crash
    • 文案:[Content] Update welcome text
  2. 描述要求

    • 功能说明/修复内容:简要描述此次更改的目的和范围。
    • 相关的 Issue 链接:关联对应的任务或问题,便于追踪。
    • 测试用例/测试结果:说明如何测试此次更改,确保功能或修复的有效性。
    • 需要注意的事项:任何需要团队成员了解的特别信息。
  3. Code Review 要点

    • 代码规范性:遵循团队的代码风格和最佳实践。
    • 业务逻辑正确性:确保代码的逻辑符合需求和预期。
    • 性能影响评估:评估此次更改是否对系统性能有负面影响。
    • 测试覆盖情况:确保新增或修改的功能配有充分的测试。

3.2 MR 状态流转

  1. 待审核

    • MR 提交后处于初始状态。
    • 指定审核人员,添加必要的标签。
  2. 审核中

    • 审核人员开始审查代码,提出修改意见。
    • 开发者根据反馈进行修改,更新 MR。
    • 可能经历多轮反馈和修改,直至满足审核要求。
  3. 待合并

    • 审核通过,等待合并操作。
    • 检查是否存在合并冲突,如有需先解决。
  4. 已合并/已关闭

    • MR 成功合并到目标分支,或因特殊原因关闭。
    • 合并后自动触发相应的发布流程(如有配置 CI/CD)。

4、关键规范与约定

4.1 分支命名规范

保持分支命名的一致性和可读性,便于识别和管理。

  1. 功能分支

    • 格式feature/name-description
    • 示例feature/playlist-management
  2. 修复分支

    • 格式hotfix/issue-description
    • 示例hotfix/player-crash-fix
  3. 文案分支

    • 格式content/page-description
    • 示例content/welcome-page-update

4.2 提交信息规范

采用统一的提交信息格式,便于历史追踪和自动化工具解析。

  1. 格式要求

    <type>(<scope>): <subject>

    <body>

    <footer>
  2. 类型说明

    • feat: 新功能
    • fix: BUG修复
    • docs: 文档更新
    • style: 格式调整(不影响代码逻辑)
    • refactor: 重构(不增加功能或修复BUG)
    • test: 测试相关
    • chore: 构建变动或工具更新

5、常见问题处理

  1. 多功能并行开发

    • 每个功能使用独立的 feature 分支,避免相互干扰。
    • 通过 testing 分支统一管理测试,确保所有功能在同一测试环境中集成。
    • 按照优先级顺序分别合并到 master,保持发布的有序性。
  2. 测试环境损坏

    • 可从 master 分支重新创建 testing 分支,确保测试环境的可用性。
    • 需要重新合并待测功能,确保所有必要的变更被包含。
  3. 合并冲突处理

    • master 分支为基准解决冲突,确保线上代码的稳定性。
    • 在解决冲突前,与相关团队成员沟通,避免重复和错误修改。
    • 使用 Git 的冲突解决工具,逐步排查并解决冲突。

实践篇:完整示例

项目背景

为了更好地理解上述工作流,下面通过一个具体的项目实践示例来展示其应用。

项目名称:MusicApp

项目需求

  1. 开发新的播放列表功能
  2. 修复播放器中的一个紧急 BUG
  3. 更新欢迎页的文案内容

实践步骤

1. 新功能开发

需求:开发一个新的播放列表功能,允许用户创建、编辑和删除播放列表。

步骤详解

  1. 创建功能分支

    # 切换到 master 分支,确保基于最新代码
    git checkout master
    git pull origin master
    # 创建并切换到 feature 分支
    git checkout -b feature/playlist

    注释

    • git checkout master:切换到主分支,确保从最新的代码开始。
    • git pull origin master:拉取远程主分支的最新更改,避免分支落后。
    • git checkout -b feature/playlist:创建并切换到新的功能分支,后续所有开发在此分支进行。
  2. 开发功能并提交

    # 添加所有更改到暂存区
    git add .
    # 提交更改,采用规范的提交信息
    git commit -m "feat: add playlist feature"
    # 推送分支到远程仓库
    git push origin feature/playlist

    注释

    • git add .:将当前目录下所有更改添加到暂存区,准备提交。
    • git commit -m "feat: add playlist feature":提交更改,并添加清晰的提交信息,描述此次更改的目的。
    • git push origin feature/playlist:将本地的 feature 分支推送到远程仓库,以便团队成员进行 Code Review 和协作。
  3. 提交 MR 到 testing

    • 在 AtomGit 上创建 MR
      • 选择 feature/playlist 分支为源分支,testing 为目标分支。
    • 指定 Code Review 人员
      • 选择负责审查代码的团队成员,确保代码质量。
    • 解决 Review 意见并更新 MR
      • 根据审查意见在 feature 分支上进行修改,重复推送和更新 MR,直至审查通过。
  4. 测试通过后提交 MR 到 master

    • 再次进行 Code Review
      • 在合并到 master 前,进行最后的代码审查,确保无遗漏。
    • 确认无误后合并到 master
      • 通过审查后,将功能分支合并到 master 分支。
  5. 合并后操作

    # 切换回 master 分支
    git checkout master
    # 拉取最新的 master 分支代码
    git pull origin master
    # 合并 feature 分支到 master
    git merge feature/playlist
    # 打 tag 标记发布版本
    git tag -a v1.1.0 -m "Release playlist feature"
    # 推送 master 分支和 tags 到远程仓库
    git push origin master --tags

    # 删除本地 feature 分支
    git branch -d feature/playlist
    # 删除远程 feature 分支
    git push origin --delete feature/playlist

    注释

    • git checkout mastergit pull origin master:确保本地 master 分支与远程同步。
    • git merge feature/playlist:将功能分支的更改合并到 master
    • git tag -a v1.1.0 -m "Release playlist feature":为此次发布打上版本标签,便于版本管理和回溯。
    • git push origin master --tags:将 master 分支和标签推送到远程仓库。
    • git branch -d feature/playlistgit push origin --delete feature/playlist:删除本地和远程的 feature 分支,保持分支整洁。

2. BUG 修复

需求:修复播放器中的一个紧急 BUG,导致部分用户无法正常播放音频。

步骤详解

  1. 创建修复分支

    # 切换到 master 分支
    git checkout master
    # 拉取最新的 master 分支代码
    git pull origin master
    # 创建并切换到 hotfix 分支
    git checkout -b hotfix/player-crash

    注释

    • git checkout mastergit pull origin master:确保基于最新的稳定代码进行修复。
    • git checkout -b hotfix/player-crash:创建一个 hotfix 分支,专门用于修复紧急 BUG。
  2. 修复 BUG 并提交

    # 添加修复后的代码到暂存区
    git add .
    # 提交修复,采用规范的提交信息
    git commit -m "fix: player crash issue"
    # 推送修复分支到远程仓库
    git push origin hotfix/player-crash

    注释

    • git add .:将修复后的文件添加到暂存区。
    • git commit -m "fix: player crash issue":提交修复,明确描述此次更改的目的。
    • git push origin hotfix/player-crash:将修复分支推送到远程仓库,以便进行 MR 和快速上线。
  3. 如非紧急,先提交 MR 到 testing

    • 在 AtomGit 上创建 MR
      • 选择 hotfix/player-crash 分支为源分支,testing 为目标分支。
    • 进行测试验证
      • testing 环境中验证 BUG 是否已修复,确保稳定性。
  4. 测试通过后提交 MR 到 master

    • 进行 Code Review
      • 审查修复代码,确保没有遗漏或引入新问题。
    • 合并发布 MR
      • 通过审查后,将修复合并到 master 分支,并进行发布。
  5. 合并后操作

    # 切换回 master 分支
    git checkout master
    # 拉取最新的 master 分支代码
    git pull origin master
    # 合并 hotfix 分支到 master
    git merge hotfix/player-crash
    # 推送 master 分支到远程仓库
    git push origin master

    # 删除本地 hotfix 分支
    git branch -d hotfix/player-crash
    # 删除远程 hotfix 分支
    git push origin --delete hotfix/player-crash

    注释

    • git checkout mastergit pull origin master:确保本地 master 分支与远程同步。
    • git merge hotfix/player-crash:将修复分支的更改合并到 master
    • git push origin master:将 master 分支的最新更改推送到远程仓库。
    • git branch -d hotfix/player-crashgit push origin --delete hotfix/player-crash:删除本地和远程的 hotfix 分支,保持分支整洁。

3. 文案更新

需求:更新应用内的欢迎页文案,使其更加友好和简洁。

步骤详解

  1. 创建文案分支

    # 切换到 master 分支
    git checkout master
    # 拉取最新的 master 分支代码
    git pull origin master
    # 创建并切换到文案分支
    git checkout -b content/welcome-text-update

    注释

    • git checkout mastergit pull origin master:确保基于最新的稳定代码进行文案更新。
    • git checkout -b content/welcome-text-update:创建一个内容更新分支,专门用于文案修改。
  2. 更新文案并提交

    # 编辑 welcome.md 或相应的文案文件
    # 添加修改后的文件到暂存区
    git add welcome.md
    # 提交更改,采用规范的提交信息
    git commit -m "content: update welcome message"
    # 推送文案分支到远程仓库
    git push origin content/welcome-text-update

    注释

    • 编辑相关文案文件,确保内容准确且符合需求。
    • git add welcome.md:将修改后的文案文件添加到暂存区。
    • git commit -m "content: update welcome message":提交更改,描述此次文案更新的目的。
    • git push origin content/welcome-text-update:将文案分支推送到远程仓库,以便进行 MR 和文案验证。
  3. 提交 MR 到 testing

    • 在 AtomGit 上创建 MR
      • 选择 content/welcome-text-update 分支为源分支,testing 为目标分支。
    • 进行文案验证
      • 由运营团队或相关人员进行文案审核,确保内容的准确性和合适性。
  4. 验证通过后提交 MR 到 master

    • 进行 Code Review
      • 审查文案更新,确保没有语法或内容上的错误。
    • 合并发布
      • 通过审核后,将文案分支合并到 master 分支,并进行发布。
  5. 合并后操作

    # 切换回 master 分支
    git checkout master
    # 拉取最新的 master 分支代码
    git pull origin master
    # 合并文案分支到 master
    git merge content/welcome-text-update
    # 推送 master 分支到远程仓库
    git push origin master

    # 删除本地文案分支
    git branch -d content/welcome-text-update
    # 删除远程文案分支
    git push origin --delete content/welcome-text-update

    注释

    • git checkout mastergit pull origin master:确保本地 master 分支与远程同步。
    • git merge content/welcome-text-update:将文案分支的更改合并到 master
    • git push origin master:将 master 分支的最新更改推送到远程仓库。
    • git branch -d content/welcome-text-updategit push origin --delete content/welcome-text-update:删除本地和远程的文案分支,保持分支整洁。

效果验证

通过这套工作流,我们实现了以下目标:

  • 功能开发的独立性:每个功能在独立的分支上开发,避免互相影响。
  • BUG 修复的及时性:紧急 BUG 能够迅速修复并上线,保持产品稳定。
  • 文案更新的规范性:所有文案修改经过严格的审核和验证,确保内容质量。
  • 分支管理的清晰性:通过明确的分支命名和管理策略,团队成员能够快速理解和操作。

推荐阅读

  1. Git 与 AtomGit 实践:从零到一

    • 适合 Git 初学者的入门指南。
  2. Git 与 AtomGit 实践:贡献协作

    • 详细介绍团队协作的最佳实践。
  3. Git 与 AtomGit 实践:项目维护

    • 详细介绍代码审查和合并的最佳实践。

通过这套工作流程,团队可以更高效地进行协作开发。希望本文对你有所帮助!

· 10 min read
Kyle

引言

你是否曾想参与开源项目但不知从何下手?或者对开源协作流程感到困惑?本文将通过一个真实的案例,带你体验开源协作的完整流程。我们以 OpenLinkSaaS(凌鲨)项目为例,详细讲解如何从一个普通用户成长为开源贡献者。

OpenLinkSaaS 项目简介

OpenLinkSaaS(凌鲨)是一个正在基金会孵化筹备期的开源项目,旨在为软件开发团队提供效能提升工具。项目目前托管在 AtomGit 平台上,其中最重要的产品之一就是 AtomGit 桌面客户端,这是一个由 OpenLinkSaaS 开发和维护的开源工具,为开发者提供了便捷的代码托管和版本控制体验。

AtomGit 桌面客户端简介

AtomGit 桌面客户端是 OpenLinkSaaS 项目的核心产品,它为开发者提供了图形化的界面来管理代码仓库、执行版本控制操作,使得代码协作变得更加简单直观。作为一个开源项目,它不仅服务于开发者,也欢迎开发者参与其改进和功能扩展。

开源协作的三个角色

在开源项目中,通常存在三类主要角色:

  1. 使用者:项目的最终用户
  2. 贡献者:为项目贡献代码的开发者
  3. 维护者:负责项目管理和代码审核的管理员

让我们通过一个完整的需求实现流程,来看看这三个角色是如何协作的。

实战步骤

1. 提出需求(使用者视角)

作为一名 AtomGit 桌面客户端的用户,当你发现了新的需求或改进建议时,有两种便捷的方式提交反馈:

方式一:通过客户端直接反馈

  1. 打开 AtomGit 桌面客户端
  2. 点击右上角的反馈按钮"😊"
  3. 你将被直接带到项目的 Issue 反馈区域

方式二:在代码仓库页面提交

  1. 访问项目仓库:https://atomgit.com/openlinksaas-org/desktop
  2. 点击 "Issues" 标签页
  3. 创建新的 Issue,描述你的需求

提示:无论选择哪种方式,请尽可能详细地描述你的需求,包括:

  • 具体的使用场景
  • 期望达到的效果
  • 如果可能的话,提供相关的截图或示例

这样的反馈更容易被开发者理解和采纳!

2. 贡献代码(贡献者视角)

第一步:环境准备

在开始贡献代码之前,请确保你已经:

  • 安装了 Git
  • 注册了 AtomGit 账号
  • 安装了必要的开发环境(Node.js、Rust 等)
  • 阅读了项目的开发文档

第二步:需求理解

在开始编码之前,最重要的是充分理解需求:

  1. 仔细阅读 Issue 描述内容
  2. 如有不明确的地方,在 Issue 下评论与提出者讨论
  3. 确保你的理解与用户需求一致

第二步:Fork 项目

- 访问 https://atomgit.com/openlinksaas-org/desktop
- 点击右上角的 "Fork" 按钮
- 项目将被复制到你的个人仓库

第三步:克隆和开发

你可以选择以下两种方式之一进行开发:

方式一:使用 AtomGit 桌面客户端(推荐)
  1. 打开 AtomGit 桌面客户端
  2. 点击"克隆仓库",输入你 Fork 后的仓库地址
  3. 选择本地存储路径
  4. 进行代码修改
  5. 在客户端中提交修改,填写提交信息

方式二:使用 Git 命令行
# 克隆仓库
git clone git@atomgit.com:kyle/desktop.git

# 创建新分支( 可选,默认为 master 分支)
git checkout -b feature-xxx

# 提交修改
git add .
git commit -m "feat: add new feature #123"
git push origin feature-xxx

提交规范

一个好的代码提交信息应该包含:

  • 修改类型:feat/fix/docs/style/refactor 等
  • 简要说明修改内容
  • 关联的 Issue 编号,如 #123

示例:

feat: enable minapp feature #123

- Changed enable_minapp flag to true in vendor_config.rs
- Added new configuration options for minapp
- Updated related documentation

3. 代码审核(维护者视角)

第一步:需求确认

作为维护者,首要任务是确保理解用户需求:

  1. 仔细阅读相关 Issue 的原始需求描述
  2. 查看需求讨论过程中的所有评论
  3. 确认提交的代码是否完全满足用户需求

第二步:代码审查(CR)

在 AtomGit 代码托管平台上进行变更请求审查:

  1. 检查代码实现逻辑
  2. 审核代码规范性
  3. 测试功能是否符合预期
  4. 提供审查意见:
    • 如需修改,在相关代码处添加评论
    • 若代码符合要求,批准变更请求
  5. 决定是否合并(Merge)到主分支

第三步:编译发版

完成代码合并后,需要进行版本发布:

  1. 更新版本号
  2. 编译新版本
  3. 运行完整测试套件
  4. 编写版本更新说明
  5. 发布新版本

第四步:完成反馈

有多种方式可以完成反馈循环:

方式一:在 Issue 中回复
  1. 访问原始 Issue
  2. 回复用户功能已实现
  3. 说明具体更新的版本号
  4. 手动关闭 Issue
方式二:通过 Commit Message 关闭

在合并时的 commit message 中使用关键词:

feat: implement new feature (Closes #123)

fix: resolve bug (Fixed #123)

支持的关键词包括:

  • close, closes, closed
  • fix, fixes, fixed
  • resolve, resolves, resolved

维护者检查清单

  • 确认需求理解准确
  • 代码实现完整正确
  • 测试用例覆盖充分
  • 文档更新完备
  • 代码风格符合规范
  • 性能影响评估
  • 安全性评估
  • 版本发布成功
  • 用户反馈完成

注意事项

  • 保持与用户和贡献者的良好沟通
  • 及时响应代码审查请求
  • 定期整理和归档已完成的 Issue
  • 维护项目更新日志
  • 确保版本发布流程规范

成果验证

当新版本发布后,用户就能收到更新提醒,体验到新功能了!

小贴士

  1. 提交 Issue 前先搜索是否已存在类似需求
  2. 代码提交前确保通过本地测试
  3. CR 描述要清晰,便于维护者理解

结语

通过这个实例,你应该对开源协作流程有了直观的认识。参与开源项目不仅能提升技术能力,还能结识志同道合的开发者。希望这篇教程能帮助你迈出参与开源的第一步!

欢迎来到 【AtomGit】 关注 OpenLinkSaaS 项目 或者在上面探索更多开源项目,开启你的开源之旅,期待你的贡献!

常见问题解答(FAQ)

Q1: 如何处理代码冲突?

当遇到代码冲突时:

  1. 先同步上游仓库的最新代码
  2. 在本地解决冲突
  3. 提交解决后的代码

Q2: CR被要求修改怎么办?

  1. 仔细阅读审核意见
  2. 在原分支上进行修改
  3. 提交新的更改
  4. CR会自动更新

Q3: 如何撤销已提交的CR?

  1. 可以在CR页面点击"Close pull request"按钮关闭CR
  2. 如需重新提交,可以创建新的CR

· 6 min read
Kyle

教程最终效果预览:https://kaiyuanxiaobing.atomgit.net/my-blog-website/

最终效果预览

目录结构参考

完成后的项目结构应该类似这样:

项目结构

准备工作

在开始之前,我们需要安装和配置一些必要的工具:

1. 账号准备

AtomGit 首页

2. 必要工具安装

Git 安装

根据你的操作系统选择对应的安装方式:

  • Windows: 下载并安装 Git for Windows
  • macOS: 使用 Homebrew 安装:brew install git
  • Linux: 使用包管理器安装,如 Ubuntu:sudo apt-get install git

Hugo 安装

选择适合你系统的安装方式:

  • Windows: 下载并安装 Hugo for Windows
  • macOS: 使用 Homebrew:brew install hugo
  • Linux: 使用包管理器安装,如 Ubuntu Snap:sudo snap install hugo

3. Git 配置

打开终端,配置你的 Git 用户信息:

git config --global user.email "your.email@example.com"
git config --global user.name "Your Name"

1. 创建 AtomGit 仓库

我们需要创建两个仓库:

  1. my-blog-source: 存放博客源码
  2. my-blog-website: 存放生成的静态网站文件(需设为公开)

创建新仓库

重要:my-blog-website 仓库必须设置为"公开"类型,否则 Pages 将无法正常访问。

设置仓库为公开

2. 配置 SSH 访问

  1. 按照 AtomGit 官方文档 配置 SSH 密钥
  2. 获取仓库的 SSH URL

获取仓库 URL

  1. 克隆源码仓库到本地:
git clone git@atomgit.com:你的用户名/my-blog-source.git
cd my-blog-source

克隆仓库

3. 初始化 Hugo 站点

  1. 在 my-blog-source 目录下初始化 Hugo:
hugo new site . --force

初始化 Hugo

  1. 安装主题 从 Hugo 主题库 选择一个主题,这里我们使用 ananke 主题:
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

安装主题

  1. 配置主题 编辑 hugo.toml 文件:
theme = "ananke"

配置主题

4. 创建和预览内容

  1. 创建新文章:
hugo new posts/my-first-post.md

创建文章

  1. 编辑文章内容:

编辑文章

  1. 本地预览:
hugo server -D

本地预览命令

访问 http://localhost:1313 查看效果:

预览效果

5. 部署到 AtomGit Pages

  1. 初始化网站目录并配置输出路径:
cd ..
mkdir my-blog-website
cd my-blog-source

编辑 hugo.toml 文件,添加输出路径配置:

publishDir = "../my-blog-website"
  1. 初始化网站仓库:
cd ../my-blog-website
git init
git remote add origin git@atomgit.com:你的用户名/my-blog-website.git
  1. 编译并发布:
cd ../my-blog-source
hugo
cd ../my-blog-website
git add .
git commit -m "Initial website deployment"
git push -u origin master
  1. 开启 Pages 功能: 在 AtomGit 仓库设置中启用 Pages 功能:

开启 Pages

自动化部署脚本

为了简化部署过程,你可以使用以下自动化脚本:

Windows 脚本 (update_blog.bat)

@echo off
setlocal EnableDelayedExpansion

:: 配置信息
set SOURCE_DIR=my-blog-source
set WEBSITE_DIR=my-blog-website

:: 执行部署
cd %SOURCE_DIR% || (
echo Failed to enter source directory
exit /b 1
)

hugo || (
echo Hugo build failed
exit /b 1
)

git add .
git commit -m "Update blog source" || (
echo No changes to commit in source
)
git push origin master || (
echo Failed to push source
exit /b 1
)

cd ..\%WEBSITE_DIR% || (
echo Failed to enter website directory
exit /b 1
)

git add .
git commit -m "Update blog content" || (
echo No changes to commit in website
)
git push origin master || (
echo Failed to push website
exit /b 1
)

echo Deployment completed successfully!

Unix 脚本 (update_blog.sh)

#!/bin/bash

# 配置信息
SOURCE_DIR="my-blog-source"
WEBSITE_DIR="my-blog-website"

# 错误处理函数
handle_error() {
echo "Error: $1"
exit 1
}

# 执行部署
cd $SOURCE_DIR || handle_error "Failed to enter source directory"

hugo || handle_error "Hugo build failed"

git add .
git commit -m "Update blog source" || echo "No changes to commit in source"
git push origin master || handle_error "Failed to push source"

cd ../$WEBSITE_DIR || handle_error "Failed to enter website directory"

git add .
git commit -m "Update blog content" || echo "No changes to commit in website"
git push origin master || handle_error "Failed to push website"

echo "Deployment completed successfully!"

提示:使用脚本前,请确保替换了相应的用户名和路径。

故障排除

  • Pages 部署后无法访问:检查仓库是否为公开类型,确保 Pages 功能已启用。
  • Hugo 构建错误:确认 Hugo 安装正确,检查主题配置。
  • Git 推送失败:检查 SSH 密钥配置,确保网络连接正常。

参考资源


现在你已经成功搭建了自己的静态博客网站!遇到问题,可以再次反馈

· 6 min read
Kyle

0、前提条件

可能有的人是首次使用,那么我们可以尽量全面介绍,照顾到细节。 为了简化操作的复杂度,尽量全部用 GUI 的形式来操作。

  • Windows11
  • Python3
  • NodeJS v20.12.2
  • Git Client:OpenLinkSaaS

1、安装所需软件和运行环境配置

1)安装 Python

推荐使用 Anaconda 进行 Python 开发,它集成了 Python 解释器和常用的科学计算库,方便管理环境和软件包,尤其适合数据科学、机器学习等领域。

image.png image.png image.png

  • 验证 Python 安装成功

image.png

2)安装NodeJS

image.png image.png image.png image.png

  • 验证 NodeJS 安装成功

image.png

3)安装OpenLinkSaaS

image.png image.png image.png

2、下载开源项“开放原子开源活动贡献榜”

2.1、用你的 AtomGit 登录 OpenLinkSaaS

image.png image.png

2.2、设置 SSH,让你的本地电脑和AtomGit 进行通信

  • 生成 SSH Key

image.png

  • 复制 SSH Key 公钥

image.png

  • 在 AtomGit 中设置此公钥

image.png

2.3、推荐使用 SSH 方式下载克隆

image.png image.png image.png image.png

3、数据转换

进入“开放原子开源活动贡献榜”项目的“src”目录

image.png

在“src”目录下,打开终端

image.png

安装python 项目的依赖包:pandas

pip install pandas image.png

执行命令python3 .\convert.py

4、项目test & build

1) test

进入“开放原子开源活动贡献榜”根目录,并且打开终端

注意,以下操作都在 master分支操作。

  • 安装 Nodejs 的 NPM 包依赖,执行下面命令

npm install

  • 上线前本地查看数据和站点的渲染,执行命令

    用于在开发模式下运行应用。 打开 http://localhost:3000 在浏览器中查看。如果你进行了编辑,页面将重新加载。 你还将在控制台中看到任何 lint 错误。

npm start

image.png

2) 推送到 master 分支

此时从本地看数据和页面如果都没有什么问题,那么可以先推送到 master 分支。

这里推荐两种操作方式二选一。

方式一:用 OpenLinkSaaS 操作

  • 添加并提交有变化的文件 image.png

  • 把提交了变更的数据推送到 AtomGit 远端仓库 image.png

  • 检查更新成功 image.png image.png

方式二:用 Git 命令操纵

分别执行命令

git add ./
git commit -m '更新说明'
git push

3) build

  • npm run build,此时会产生的静态文件都将会在 "build目录"中。

4) 切换到build分支,执行静态文件编译

从此处开始,操作都将会在build 分支操作。

4-1)这里推荐两种操作方式二选一。

方式一:用 OpenLinkSaaS 操作 image.png

  • 接着手动删除“build目录”和“.gitignore”文件之外的所有文件。
  • 手动把“build目录”里面的所有内容都移动到“build目录”之外,也就是和“build目录”同级别。再把“build目录”删除。 17dd5850df728b8e0743967d8a372f8.png

推送到远端 AtomGit 上的 build 分支

  • 添加&提交 image.png

  • 把提交了变更的数据推送到 AtomGit 远端仓库 image.png image.png

  • 检查更新成功 image.png

方式二:用 Git 命令操作

git checkout build
  • 接着手动删除“build目录”和“.gitignore”文件之外的所有文件。
  • 手动把“build目录”里面的所有内容都移动到“build目录”之外,也就是和“build目录”同级别。再把“build目录”删除。 17dd5850df728b8e0743967d8a372f8.png

推送到远端 AtomGit 上的build 分支

git add .
git commit -m '更新说明'
git push
  • 检查更新成功 image.png

5、访问远端仓库地址查看更新

  • 访问仓库地址,查看是否更新了数据。
  • 如果没有请进入仓库的“设置”->"Pages",手动点击下“保存”按钮,将会更快的刷新最新的数据。如下图。 b755add1ec515c4a77aeacbebb1a8ea.png

以上。