引言​

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

OpenLinkSaaS 项目简介​

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

AtomGit 桌面客户端简介​

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

开源协作的三个角色​

在开源项目中，通常存在三类主要角色：

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

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

实战步骤​

1. 提出需求（使用者视角）​

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

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

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

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

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

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

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

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

2. 贡献代码（贡献者视角）​

第一步：需求理解​

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

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

第二步：Fork 项目​

- 访问 https://atomgit.com/openlinksaas/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. PR 描述要清晰，便于维护者理解

结语​

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

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

最终效果地址：https://kaiyuanxiaobing.atomgit.net/my-blog-website/

准备工作​

在开始之前，请确保你已经有了以下条件：

1. 一个 AtomGit 账户。
2. 安装 Git：

• Windows：下载并安装 Git for Windows。
• macOS：
  • 首先，检查是否已经安装了 Git：在终端中运行 git --version。
  • 如果未安装，使用 Homebrew 安装 Git：brew install git。
  • 如果已安装，但版本较旧，可以使用 Homebrew 更新 Git：brew update && brew upgrade git。
• Linux：
  • 首先，检查是否已经安装了 Git：在终端中运行 git --version。
  • 如果未安装，使用你的包管理器安装 Git（例如，在 Ubuntu 上使用 sudo apt-get update && sudo apt-get install git）。
  • 如果已安装，但版本较旧，可以使用包管理器更新 Git（例如，在 Ubuntu 上使用 sudo apt-get update && sudo apt-get upgrade git）。

3. 安装 Hugo： 静态博客系统有很多，可以根据自己的喜好选择，本教程选择用 hugo。

• Windows：下载并安装 Hugo for Windows。
• macOS：使用 Homebrew 安装 Hugo (brew install hugo) 或者下载 Hugo for macOS。
• Linux：使用 Snap 安装 Hugo (sudo snap install hugo) 或者下载 Hugo for Linux。

4. 配置 Git 用户信息： 在终端中运行以下命令来设置你的用户名和电子邮件地址：

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

1：创建 AtomGit 仓库​

1. 登录你的 AtomGit 账户

• https://atomgit.com

2. 创建两个新的仓库：my-blog-source 和 my-blog-website

注意：my-blog-website 仓库需要设置为“公开”类型，否则Pages将无法正确的访问。

2：克隆仓库到本地​

1. 生成和添加 SSH 密钥： 如果你还没有为 AtomGit 生成 SSH 密钥，请按照AtomGit 的官方文档，配置SSH密钥 中的说明进行操作。 确保你的 SSH 密钥已经添加到你的 AtomGit 账户设置中。

2. 获取my-blog-source的仓库URL

git@atomgit.com:kaiyuanxiaobing/my-blog-source.git

3. 在你的电脑上打开终端或命令提示符，使用 cd 命令切换到你想要存放博客项目的文件夹。比如本教程中是“ C:\Users\User”

4. 克隆 my-blog-source 仓库：

git clone 你的用户名/my-blog-source.git

本教程中是：git clone git@atomgit.com:kaiyuanxiaobing/my-blog-source.git

5. 进入克隆下来的仓库目录：

cd my-blog-source

3：初始化 Hugo 站点​

1. 在 my-blog-source 目录下运行以下命令初始化 Hugo 站点：

hugo new site .

🙌注意：如果该目录下不是空的，请使用--force参数，如下图。

2. 安装一个 Hugo 主题。

hugo 有非常丰富的主题可供选择，请访问：https://themes.gohugo.io/。 例如，本教程使用以下命令安装 ananke 主题：

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

3. 打开 hugo.toml 文件，添加以下内容来指定你安装的主题：

theme = "ananke"

4：创建你的第一篇博客文章​

1. 使用以下命令创建一篇新文章：

hugo new posts/my-first-post.md

2. 编辑 content/posts/my-first-post.md 文件，添加你的文章内容。

5：本地预览​

1. 在 my-blog-source 目录下运行以下命令来启动本地服务器：

hugo server -D

2. 打开浏览器，访问 http://localhost:1313 来预览你的博客。

6：配置 Hugo 输出路径​

1. 打开 config.toml 文件，添加以下内容来指定编译后的输出路径：

publishDir = "../my-blog-website"

2. 将 my-blog-website 目录初始化为一个 Git 仓库，执行以下命令：

cd ..
mkdir my-blog-website
cd my-blog-website
git init

3. 将 my-blog-website 目录与 AtomGit 上的 my-blog-website 仓库关联：

• 获取“my-blog-website”仓库的远程地址。具体方法可以仓库上面的“2：克隆仓库到本地”
• 地址为：“git@atomgit.com:kaiyuanxiaobing/my-blog-website.git”

git remote add origin  你的用户名/my-blog-website.git

上面 origin 后面的内容请用你自己的“my-blog-website”地址替换。

7：编译并发布博客​

1. 通过以上，我们从本地可看到自己的站点已经可以正常运行出来了。
2. 我们需要编译，将其发布到 AtomGit 你的“my-blog-website”仓库中。执行下面的命令。

hugo
cd ../my-blog-website
git add .
git commit -m "my website init."
git push -u origin master

3. 在AtomGit设置并且开启 Pages 功能。

进入“my-blog-website”仓库的设置，找到 Pages，按照指引一步步操作。最后在仓库的设置Pages下就能看到已经安装了Pages功能，并且有了静态站点的默认 URL，本教程中是 https://kaiyuanxiaobing.atomgit.net/my-blog-website

8：线上效果​

通过以上的配置和操作，我们就可以实现撰写、编译和部署自己的静态网站到 AtomGit 的 Pages 上了。如下图，教程的最终结果如下。

教程发布后的地址：https://kaiyuanxiaobing.atomgit.net/my-blog-website/

附：用脚本自动化执行：编译并发布​

如果用了下面的自动化脚本之后，最终的“my-blog-source”目录结构可能是这样，但也不是一定。

运行相应的脚本（根据你的操作系统选择对应的脚本）。

Windows (批处理文件)​

将下面的代码保存为 update_blog.bat 文件，然后在命令提示符或 PowerShell 中运行它。

@echo off

:: 定义仓库路径和远程仓库 URL
set SOURCE_DIR=my-blog-source
set WEBSITE_DIR=my-blog-website
set SOURCE_REPO_URL=git@atomgit.com:yourusername/my-blog-source.git
set WEBSITE_REPO_URL=git@atomgit.com:yourusername/my-blog-website.git

:: Configure Git user identity
git config --global user.email "你自己的邮箱"
git config --global user.name "你自己的用户名"

:: 构建 Hugo 站点
cd %SOURCE_DIR%
hugo

:: 将源博客数据推送到远程仓库
git add .
git commit -m "Update blog source"
git push origin master

:: 将生成的文件添加到网站仓库并推送
cd ..\%WEBSITE_DIR%
git add .
git commit -m "Update blog content"
git push origin master

echo Blog source and website updated and pushed to AtomGit Pages.

macOS 和 Linux (Bash 脚本)​

将下面的代码保存为 update_blog.sh 文件，并赋予它执行权限：

#!/bin/bash

# 定义仓库路径和远程仓库 URL
SOURCE_DIR="my-blog-source"
WEBSITE_DIR="my-blog-website"
SOURCE_REPO_URL="git@atomgit.com:yourusername/my-blog-source.git"
WEBSITE_REPO_URL="git@atomgit.com:yourusername/my-blog-website.git"

# Configure Git user identity
git config --global user.email "你自己的邮箱"
git config --global user.name "你自己的用户名"

# 构建 Hugo 站点
cd $SOURCE_DIR
hugo

# 将源博客数据推送到远程仓库
git add .
git commit -m "Update blog source"
git push origin master

# 将生成的文件添加到网站仓库并推送
cd ../$WEBSITE_DIR
git add .
git commit -m "Update blog content"
git push origin master

echo "Blog source and website updated and pushed to AtomGit Pages."

然后运行：

chmod +x update_blog.sh
./update_blog.sh

请确保将 yourusername 替换为你的 AtomGit 用户名，并将 my-blog-source 和 my-blog-website 替换为你的实际仓库名称。此外，确保 Hugo 和 Git 都已经添加到你的系统环境变量中，以便脚本可以在命令行中找到这些工具。

参考资料​

• hugo：https://gohugo.io/
• ananke：https://github.com/theNewDynamic/gohugo-theme-ananke

• 项目地址：https://atomgit.com/lijin/open-atom-contributor-leaderboard/

0、前提条件​

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

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

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

1）安装 Python​

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

• 下载地址 https://www.python.org/downloads/
• 双击安装 Python3 软件

• 验证 Python 安装成功

2）安装NodeJS​

• 下载地址 https://nodejs.org/dist/v20.12.2/node-v20.12.2-x64.msi

• 双击安装 NodeJS

• 验证 NodeJS 安装成功

3）安装OpenLinkSaaS​

• 下载地址：https://www.linksaas.pro/download
• 双击安装

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

2.1、用你的 AtomGit 登录 OpenLinkSaaS​

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

• 生成 SSH Key

• 复制 SSH Key 公钥

• 在 AtomGit 中设置此公钥

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

3、数据转换​

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

在“src”目录下，打开终端​

安装python 项目的依赖包：pandas​

pip install pandas

执行命令python3 .\convert.py​

4、项目test & build​

1） test

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

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

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

npm install

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

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

npm start

2） 推送到 master 分支

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

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

方式一：用 OpenLinkSaaS 操作

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

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

• 检查更新成功

方式二：用 Git 命令操纵

分别执行命令

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

3） build

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

4） 切换到build分支，执行静态文件编译

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

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

方式一：用 OpenLinkSaaS 操作

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

推送到远端 AtomGit 上的 build 分支

• 添加&提交

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

• 检查更新成功

方式二：用 Git 命令操作

git checkout build

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

推送到远端 AtomGit 上的build 分支

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

• 检查更新成功

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

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

以上。