不少同学想要参与开源项目,却不知道该从哪里起步
最近我接触到了 soduwork 项目,试着给它提交PR
在这里把自己的开发实操过程记录下来,希望能给同样想要踏入开源的同学提供一份参考
简单的基本流程:
- 看到项目 → Star 收藏
- Fork 仓库到自己账号
- 本地克隆自己 Fork 的仓库,新建分支开发
- 发现问题 / 要做功能,先看 Issue
- 写完代码,提交(带 DCO Signed-off-by)
- 打开 PR,请求上游合并你的改动
区分Fork和Branch:
Fork 是整个仓库副本(账号级别):
原仓库你没有写权限,这个副本你拥有完整读写权限,可以随便新建分支、改代码、推送
Branch 是仓库内的分支(代码版本线):
同一个仓库内部,分出一条独立开发线,不污染主分支
即使Fork了也不要在自己的Fork副本直接主分支开发,依旧新建branch开发
issue
用来提 Bug、提需求、问问题、讨论方案【项目的 讨论/工单 区域】
分为bug /feature(新功能提案)/docs /good-first-issue(新手友好任务)
如果你想改某个功能,先搜有没有相关 Issue;没有的话可以新建 Issue 说明自己想做什么,简单跟维护者确认,得到大致认可再开始写代码,减少无效劳动
- Open :未解决、开放中(Open = 还没人修好、还在待处理)
- Closed :已经关闭(解决了),一般是 Bug 修好、需求做完,维护者关掉这个 Issue


注意事项
- 提交 commit 写清晰的说明,不要写
update、改代码这种模糊信息,尽量简短描述做了什么改动,例:优化页面开场白文案 - 只提交本次需求相关的改动,不要顺带批量格式化一堆无关文件、乱改缩进,会干扰审核,增大维护者 review 负担
- 同步上游代码:本地经常拉取原项目最新代码,避免你的 PR 出现大量代码冲突
- 不要上来就提新增大功能,大型新特性一般需要先讨论方案
- 不要忽视文档:改了功能,如果有文档也要同步更新文档
对于3:如果你只 git pull origin main,拉的只是你自己 Fork 副本 的代码,别人在原项目提交的新改动,你是拿不到的!这就是很多人 PR 一堆冲突的根源
正确操作是同步上游:
bash
# 只需要配置一次
git remote add upstream https://github.com/mdiri-ai/SoduWork.git
# 拉取原项目最新代码
git fetch upstream
# 把上游main合并到你本地干净的main
git checkout main
git merge upstream/main
# 同步回你自己Fork仓库的main(可选,保持网页上Fork仓库也是最新)
git push origin main
新建Fork
直接确定就行

建好后本地应Clone的是自己fork的仓库而非原仓库
配置上游代码,防止后期拉去代码没能拉取原代码(AI干就行了)
看issue找自己想做的
assigner是官方证明有人做了,空的一般就可以试着完成

程序启动
尽量还是先跑一跑程序,多了解一下项目,现在ai很nb直接都帮我弄好了:


git fetch:从远程仓库把最新的代码、分支、提交记录下载到本地,但不会自动合并到你当前分支,不会改动你本地正在写的代码,什么时候合并?:
# 1. 把原仓库添加为上游(只需要做一次)
git remote add upstream https://github.com/mdiri-ai/SoduWork.git
# 2. 拉取原仓库最新代码(fetch,只下载,不合并)
git fetch upstream
# 3. 切换到本地main,合并上游最新main
git checkout main
git merge upstream/main
# 4. 同步更新到你自己fork仓库
git push origin main
# 再切回你的功能分支继续开发
git checkout feat/220-task-result-show-token-and-elapsed-time
筛选issue
我选了一个最简单的:前端修改Show elapsed time and token usage together in task results · Issue #220 · mdiri-ai/SoduWork
正式修改
在当前fork下的主分支新建自己的当前工作分支,切换到当前分支
修改代码(这里注意提醒让ai一般习惯改完代码后直接把本地分支提交了,但是没有提交到远程,所以不用怕)
完成后推送代码(其实完全可以ai做,这里为了让大家知道流程说一下)

效果:

如果不是的话上述fork设置操作做一下
注意网络问题,在github上提交代码需要魔法否则失败,常见失败代码:

成功则:

这里其实把提交的修改更新到文档里更规范,没有写这次就算了
成功后


没有的话大概率上一步失败了
确认信息即可

提交之后,就等仓库维护者 Review、讨论、合并,你这边的提交流程就走完了
被拒绝也没事,后续坚持修改到管理者满意就可

效果:

