Chinese language support

(1)Things a non Programmer can do.zh-cn.md
(2)undoing-a-commit.zh-cn.md
(3)Useful-links-for-further-learning.zh-cn.md
(4)why-using-branches.zh-cn.md
(5)git-bash-windows-tutorial.zh-cn.md
(6)github-cli-tutorial.zh-cn.md
This commit is contained in:
JonatanRosali
2025-05-13 16:39:06 +08:00
parent 0106eff0b5
commit 28ce46db61
7 changed files with 612 additions and 33 deletions
@@ -0,0 +1,145 @@
# 非程序员可以做的事
## 从倾听开始
开源的本质是人与人之间的合作。
你想要加入一个团队,就必须了解这个社区以及它是如何运作的。
直接进入一个项目并说“嗨,我认为这个项目应该做XXX”通常不会被很好地接受。
某些项目可能欢迎这种方式,但如果项目已经运行一段时间,这种态度很难被采纳。
**倾听是了解项目真正需求的最佳方式。**
1. **加入邮件列表**
对于许多项目来说,邮件列表是关于项目开发的主要沟通渠道。在大型项目中,可能会有很多不同的邮件列表可供选择。例如,PostgreSQL 项目在其邮件列表页面上就有不少于 12 个面向用户的列表和 6 个开发者列表。
建议你一开始关注主要的用户列表和核心开发者列表来“听听看”。
2. **关注博客**
核心开发人员维护的博客通常会分享有关未来版本的计划,以及达成这些目标的过程。一个叫做 planet 的网站会汇集来自多个相关来源的新闻和博客内容。
如果某个项目有 planet 网站,比如 planet.gnome.org 或 planet.mysql.com,请从那里开始。只需在 Google 中搜索 "planet <projectname>" 即可。
3. **加入 IRC 频道**
许多开源项目都有专属的 IRC(互联网中继聊天)频道,开发者和用户会在里面讨论问题与开发进度。在项目的官方网站上通常可以找到 IRC 频道的名称和所在网络的信息。
**处理工单系统**
代码是任何开源项目的核心,但不要以为只有写代码才算是贡献。
代码的维护及其周边系统往往在开发新功能或修复 bug 的过程中被忽略。
这些部分是你进入项目的良好切入点。
大多数项目都有公开的故障工单系统,通常在项目主页和文档中就能找到链接。
它是用户与开发者之间的主要沟通渠道。
保持工单系统的更新就是一种很有价值的贡献。
你可能需要获得该系统的特别权限,一旦你表示出愿意协助维护,项目负责人通常会很乐意为你开放权限。
4. **诊断 bug**
很多 bug 报告都不够详细。
协助诊断并分析 bug 可以大大节省开发者排查问题的时间。
比如用户报告“我做了 X 操作,软件就坏了”,你可以尝试复现问题,找出具体触发条件。
这个问题是可以重复触发的吗?能不能提炼出一套步骤重现问题?是否只在某些浏览器或操作系统中才出现?
即使你不清楚问题的根本原因,但你做出的分析工作,也会让其他人更容易去修复它。
无论你发现了什么,请将其记录在工单系统中,方便所有人查看。
5. **关闭已修复的 bug**
有些 bug 虽然已经在代码中修复,但对应的工单却没有更新状态。
清理这些“陈年工单”虽然耗时,但对整个项目非常有帮助。
你可以从查询一年以前的工单开始,检查这些 bug 是否仍然存在。
阅读项目的更新日志,确认 bug 是否已被修复。
如果确定已修复,请在工单中注明修复版本并关闭工单。
也可以尝试使用最新版本重现这个 bug。
如果无法复现,请在工单中注明并关闭;如果仍存在,也请更新工单说明并保留为“打开”状态。
## 参与代码工作
不同经验水平的开发者都可以为项目贡献代码。
不要认为只有编程大神才有资格参与贡献。
如果你的工作涉及代码更改,请先了解项目是如何接受代码贡献的。
每个项目的工作流都不同,因此在提交代码之前请先询问清楚流程。
例如,PostgreSQL 项目对代码提交要求非常严格:必须以补丁形式发送到邮件列表,由核心开发者详细审查。
而 Parrot 项目则相对宽松,很容易就能获得代码库的提交权限。
如果项目托管在 GitHub 上,可能还会使用 pull request 的工作流。
没有两个项目是完全相同的。
每当你修改代码时,请务必遵守已有代码风格,使你提交的代码看起来就像是原生的一部分。
即使你不喜欢某种括号或缩进方式,也不应擅自改变已有风格。
这就像在说:“我不喜欢你们的风格,我的更好,你们应该改成我的。”
6. **测试测试版或候选版本**
如果一个项目支持多个平台,那发布前的可移植性测试就至关重要。
当项目发布 beta 或 RCRelease Candidate)版本时,项目负责人希望有人能在各种平台上进行测试。
你就可以成为其中一员,帮助确认在你的环境下也能正常运行。
通常你只需下载、构建并运行软件即可。
尤其当你使用的是较为冷门的操作系统或硬件时,你的反馈对项目非常宝贵。
7. **修复一个 bug**
这是很多想写代码的新手常见的起点。
很简单:在工单系统中找一个感兴趣的问题,尝试去修复它。
如果合适,可以在代码中添加注释记录你的修改;如果项目有测试套件,最好也为你修复的 bug 添加测试用例。
即便你没能修复 bug,也请将你调查的结果写进工单中,这对后来的人是很有帮助的。
8. **编写测试用例**
大多数项目都有测试套件,但几乎没有哪个测试覆盖是“完美”的。
可以使用测试覆盖工具(如:C 的 gcovPerl 的 Devel::Cover)找出哪些代码尚未被测试。
然后为这些部分添加测试用例。
9. **消除编译警告**
许多基于 C 的项目在编译时会有很多警告信息。
虽然多数情况下这并不影响程序运行,但会制造混乱或误导。
你可以排查警告背后是否隐藏真正的 bug。
如果没有实际问题,就修改代码消除警告,提升代码整洁度。
10. **添加注释**
当你在阅读代码时,可能会遇到令人困惑的部分。
如果你感到困惑,别人可能也会。
请在适当位置添加注释并提交补丁,帮助其他人理解代码。
## 编写文档
文档常常是被忽视的一部分。
而且很多时候文档是“内部人”写给“内部人”的,忽略了初学者视角。
如果你曾看过某个手册让你觉得:“作者好像默认我已经懂这套系统了”,你就明白我的意思了。
新人的眼睛能发现老成员早已忽视的问题。
11. **创建示例**
任何项目都不嫌示例多。
无论是 Web API、函数库、图形工具(如 Gimp)或命令行工具,
一个实用示例往往比一大堆文档更能直观说明使用方式。
对于 API 或库,可以写个简单的 demo;对于工具,展示真实的使用情景。
如果你擅长视觉内容,也可以录屏展示如何安装、配置等步骤。
## 参与社区
开源项目不仅仅是代码。社区才是开源的生命力来源。以下是你可以帮助社区的方式:
12. **回答问题**
帮助新手是社区成长的重要方式。
即使对方的问题很基础,也不要敷衍了事。
哪怕是你很想说“RTFM”,请记住:帮助他们,就等于在培养未来的维护者。
每个人都是从新手走过来的,项目要保持活力就需要不断有新人加入。
13. **写一篇博客**
如果你有博客,请写下你使用该项目的经验。
记录你遇到的问题和解决办法,这不仅可以帮助搜索到的人,也有助于传播该项目。
(顺带一提,如果你未来找工作,技术博客是一个很好的展示作品集的方式)
14. **优化网站**
如果你有网页设计技能,可以协助美化项目网站或设计 logo,提升项目的公众形象。
这些往往是开源社区中缺乏的技能,我相信很多维护者都会非常欢迎这方面的协助。
15. **编写技术文档**
如果你擅长用通俗易懂的方式说明软件原理,可以帮助项目撰写或更新技术文档。
很多开源项目都在寻找志愿者来扩展文档,尤其是面向普通大众的部分。
你不需要是程序员,只要能把话说清楚就行。
最重要的是,倾听周围人的讨论,观察有没有什么急需解决的问题。
例如,在 Parrot 项目的邮件列表中,有人提议将工单系统从 Trac 转移到 GitHub。
但由于缺乏转换工具,一度引发争论。我当时提出“我可以写一个转换器”。
大家非常欢迎这个提议。我花时间写了一个转换程序,把 450 多条工单全部迁移了过去。
这是一次很成功的贡献。开发者继续专注写代码,而我解决了一个让大家头疼的问题。
16. **教学与协助他人**
最好的学习方式就是尝试去教别人。
能用最简单的例子讲清复杂概念的老师,往往才是最厉害的。
教学不但能加深你自己的理解,也能帮助别人快速上手。
你从别人那里学到的知识,也请传递下去,让世界变得更美好。
@@ -0,0 +1,53 @@
# 实用链接
本页面致敬所有让我们生活更轻松的技巧网站、博客文章和实用链接。
无论是初学者还是资深开发者,它们都是极好的参考资源。
这个页面将作为一个索引,汇总所有对开源领域新人或想深入了解的人有帮助的链接。
## 链接列表
**请注意: 以下所有链接均为英文内容。**
1. [Git 交互式教程](https://try.github.io)
2. [YouTubeFreeCodeCamp 的 Git 和 GitHub 初学者教程](https://www.youtube.com/watch?v=RGOj5yH7evk)
3. [git - 简明指南](http://rogerdudler.github.io/git-guide/)
4. [如何撤销、更改或删除 Git 提交](http://sethrobertson.github.io/GitFixUm/fixup.html)
5. [Git 和 GitHub 教程(多语言版本)](https://github.com/Roshanjossey/first-contributions)
6. [解决合并冲突](https://www.git-tower.com/learn/git/ebook/en/command-line/advanced-topics/merge-conflicts)
7. [Git How To:解决合并冲突](https://githowto.com/resolving_conflicts)
8. [Git 基础 - 快速入门指南](https://blog.praveen.science/basics-of-git-the-quick-start-guide/)
9. [我们在 Spotify Agile 方法中使用的 Git 标准](https://blog.praveen.science/git-standards-followed-in-our-way-of-spotify-agile-methodolgy/)
10. [Git 快捷方式](https://blog.praveen.science/git-shortcuts/)
11. [官方 Git 多语言备忘单](https://services.github.com/on-demand/resources/cheatsheets)
12. [来自 Tower 的 Git 备忘单](https://www.git-tower.com/learn/cheat-sheets/git)
13. [常见 Git 问题及解决方法](https://www.codementor.io/citizen428/git-tutorial-10-common-git-problems-and-how-to-fix-them-aajv0katd)
14. [Git Rebase 图解指南](https://blog.gitprime.com/git-rebase-an-illustrated-guide/)
15. [新手 Rebasing 与 Squashing 指南](https://github.com/servo/servo/wiki/Beginner%27s-guide-to-rebasing-and-squashing)
16. [命令与文件关联的 Git 速查表](http://ndpsoftware.com/git-cheatsheet.html)
17. [如何贡献开源](https://opensource.guide/how-to-contribute/)
18. [开源贡献入门指南](https://github.com/OpenSourceHelpCommunity/Getting-Started-With-Contributing-to-Open-Sources)
19. [FreeCodeCamp 的开源贡献指南](https://github.com/freeCodeCamp/how-to-contribute-to-open-source)
20. [Atlassian 的 Git 教程](https://www.atlassian.com/git)
21. [Pull Request 审查流程](https://help.github.com/articles/about-pull-request-reviews/)
22. [另一个 Git 交互式教程](https://learngitbranching.js.org/)
23. [Git 命令行速查表](https://gist.github.com/davfre/8313299)
24. [编程书籍(免费)](https://github.com/EbookFoundation/free-programming-books)
25. [Git 专业技巧与秘籍电子书](https://goalkicker.com/GitBook/GitProfessionalTipsSecrets.pdf)
26. [成为 Git 专家的简单规则](https://medium.freecodecamp.org/follow-these-simple-rules-and-youll-become-a-git-and-github-master-e1045057468f)
27. [关于 Git 提交信息的建议](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
28. [更好的提交信息的 5 个技巧](https://thoughtbot.com/blog/5-useful-tips-for-a-better-commit-message)
29. [Git 版本控制基础](https://ourcodingclub.github.io/2017/02/27/git.html)
30. [Git 版本控制课程(Udacity](https://www.udacity.com/course/version-control-with-git--ud123)
31. [Coursera 上 Google 提供的 Git 课程(可试听)](https://www.coursera.org/learn/introduction-git-github)
32. [在 VS Code 中使用版本控制](https://code.visualstudio.com/docs/editor/versioncontrol)
33. [Git 与 GitHub 的区别以及入门方法](https://kinsta.com/knowledgebase/git-vs-github/)
34. [Hello World Github 教程](https://guides.github.com/activities/hello-world/)
35. [如何使用 GitHub](https://www.edureka.co/blog/how-to-use-github/)
36. [Git 与 GitHub 的 10 天教程](https://github.com/Asabeneh/10-days-of-git-and-github)
37. [GitHub 快捷键列表](https://docs.github.com/en/get-started/using-github/keyboard-shortcuts)
38. [Kunal Kushwaha 的 Git 和 GitHub 完整教程(YouTube](https://www.youtube.com/watch?v=apGV9Kg7ics&ab_channel=KunalKushwaha)
39. [Git 工作流速查表(Google Drive)](https://drive.google.com/uc?export=download&id=1QPRh5YmqQm4DFfitelPYlBTWC2I6tTTM)
40. [初学者 Git 工作流指南](https://medium.com/@anjulapaulus_84798/beginners-guide-to-proper-git-workflow-35a2d967734e)
41. [如何使用 GitHub Pages](https://docs.github.com/en/pages)
42. [了解 GitHub Copilot](https://docs.github.com/en/copilot/about-github-copilot/what-is-github-copilot)
持续添加你觉得有用的链接吧!
@@ -1,86 +1,88 @@
# What is squashing?
# 什么是 Squashing(压缩提交)?
In git, squashing refers to rewriting the history of your commits, so you end up with one commit with a description of the changes done.
It's usually done in open source projects because a lot of the history of a branch in open source projects is only relevant to the developer who created it, and this provides a simpler way to describe the changes made and also revert them if needed.
在 Git 中,**squashing(压缩提交)** 是指重写提交历史,把多个提交合并成一个提交,并添加一个描述性信息来说明这次更改的内容。
# How do you squash commits?
在开源项目中,这通常是常见操作,因为分支的详细历史记录往往只对原始开发者有意义。
压缩提交可以简化更改记录,也方便在需要时进行回滚。
First, perform a git log to review the commits you would like to merge in your current branch.
# 如何进行提交压缩(Squash commits)?
首先,你可以执行 `git log` 命令,查看你当前分支中要合并的提交历史:
```
git log
```
You should see a series of your commits like so:
你会看到类似这样的提交记录:
```
commit blablabla
Author: omguhh
Date: 10/10/20
Commit message 1
提交信息 1
commit blablabla2
Author: omguhh
Date: 10/10/20
Commit message 2
提交信息 2
```
So now that you see the commits you wish to merge to one, we can move along into doing that with ```git rebase```. Assuming you're already familiar with ```git rebase```, we can starting squashing commits in the interactive mode of git rebase that you can activate like so:
现在你已经找到了要合并的提交,可以使用 ```git rebase```来进行压缩。假设你已经熟悉 ```git rebase```,我们可以通过 **交互模式(interactive mode** 来进行操作:
```
git rebase -i
```
Now, with interactive rebasing you can specify the starting and end point of how far back you want to go with commits like so:
你也可以通过指定回溯的提交数来启动交互式 rebase,比如:
```
git rebase -i HEAD~2
```
Running this command will show you something like the following:
执行该命令后,你将看到类似以下内容的交互式界面:
```
pick blablabla Changing test01.txt file
pick blablabla2 Adding dummy01.txt file
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# 可用命令:
# p, pick = 使用该提交
# r, reword = 使用该提交,但修改提交信息
# e, edit = 使用该提交,但中断以进行修改
# s, squash = 使用该提交,但合并进前一个提交
# f, fixup = 类似 squash,但忽略该提交信息
# x, exec = 执行 shell 命令
#
# These lines can be re-ordered; they are executed from top to bottom.
# 你可以调整这些行的顺序,Git 会按顺序执行。
#
# If you remove a line here THAT COMMIT WILL BE LOST.
# 如果删除某一行,该提交将会丢失。
#
# However, if you remove everything, the rebase will be aborted.
# 如果删除所有行,rebase 将会被取消。
#
# Note that empty commits are commented out
# 空提交将会被注释掉。
```
So if you want to squash ```blablabla2``` into ```blablablabla```, you would change the following :
所以,如果你想将 ```blablabla2``` 压缩到 ```blablablabla```,你应该将其改成如下形式:
```
pick blablabla Changing test01.txt file
squash blablabla2 Adding dummy01.txt file
pick blablabla 更改 test01.txt 文件
squash blablabla2 添加 dummy01.txt 文件
```
If all goes well, you'd get a result that looks like this:
一切正常的话,你将看到如下合并提交的编辑界面:
```
# This is a combination of 2 commits.
# The first commit's message is:
commit message 1
# 这是两个提交的合并结果.
# 第一个提交的信息是:
提交信息 1
# This is the 2nd commit message:
# 第二个提交的信息是:
commit message 2
提交信息 2
```
That you can freely change before you decide to exit the editor to save these changes.
你可以在此自由修改合并提交的信息。
Running git log again should show you the commit message you entered before exiting the screen with the commits combined into one.
退出并保存后,执行 `git log` 命令应显示你刚刚输入的合并信息,且这两个提交已被合并为一个。
@@ -0,0 +1,59 @@
# 撤销本地提交
要撤销本地提交,只需要运行以下命令:
```
git reset
```
此命令会将暂存区(staging area)重置为你最近的一次提交,但工作目录中的更改不会被影响。
因此,你仍然可以重新提交这些更改。
如果你只是想从上一次提交中移除某个文件,可以使用以下命令:
```
git reset <文件名>
```
该命令只会将指定的文件从暂存区中移除,但文件中的更改仍然保留。
```git reset``` 使用示例:
```
# 修改了 index.php 和 tutorial.php
# 将文件添加到暂存区
$ git add .
# 想起来这两个文件应该分开提交
# 取消暂存 tutorial.php
$ git reset tutorial.php
# 先提交 index.php
$ git commit -m "Changed index.php"
# 现在提交 tutorial.php
$ git add tutorial.php
$ git commit -m "修改了 tutorial.php"
```
假设你把本地仓库搞乱了,只想恢复到最近一次提交的状态,
你可以运行以下命令:
```
git reset --hard
```
这个命令不仅会重置暂存区,还会把工作目录中的所有更改回退到最近一次提交。
其中的 ```--hard``` 模式表示 Git 会同时撤销工作目录中的所有改动。
**只有当你确定想彻底丢弃本地的所有开发内容时,才应该使用这个命令。**
```git reset --hard``` 使用示例:
```
# 决定开始一个疯狂的实验
# 创建一个新文件 'crazy.php' 并写入一些代码
# 提交 crazy.php
$ git add crazy.php
$ git commit -m "开始了疯狂的开发"
# 再次编辑 crazy.php 并修改了很多其他文件
# 提交所有被跟踪的文件
$ git add .
$ git commit -m "继续开发"
# 测试后情况失控
# 决定把所有内容撤销
$ git reset --hard HEAD~2
```
```git reset --hard HEAD~2``` 会将当前分支回退两个提交点,
同时撤销你所做的所有更改,并将这两个提交从项目历史中移除。
注意: 如果你已经将提交推送到了共享仓库,请不要执行 ```git reset --hard``` 因为这将对仓库中的其他人造成问题。
@@ -0,0 +1,71 @@
# 为什么在贡献时要使用分支
## 什么是分支?
分支(Branch)本质上是指向某个提交(commit)的指针。
当你创建分支时,Git 会基于你当前的代码状态生成一个新的快照,你可以在这个分支上自由修改,而不会影响主代码(通常是 master 分支)。
当你对实验结果满意并希望将其合并进主代码时,只需运行:
<branch name> master.
这会告诉 Git:将你在实验分支上的更改合并到 master 主分支中。
在多人参与的开源项目中,使用分支可以让每位贡献者独立开发,不影响主分支,从而更方便地合并最合适的代码。
## 它是如何工作的?
分支代表了一条独立的开发路径。
分支是编辑/暂存/提交流程的抽象表现。你可以将其想象为:为你开辟了一套新的工作目录、暂存区和项目历史。
新提交会被记录在当前分支的历史中,从而在项目历史中形成一个“分叉”。
`git branch` 命令可用于创建、列出、重命名和删除分支。
但它并不能用于切换分支或合并历史记录。因此,它通常与 `git checkout``git merge` 命令一起使用。
## 为什么要使用分支?
如果你仍然在思考“为什么我们要在版本控制中使用分支?”,那这里有一个简单的例子可以说明:
假设某款量产汽车在正式发布前需要喷漆,原定默认颜色为“橄榄绿”,但制造团队的一些成员想展示“红色”版本。
为了避免混乱,“红色喷漆”就像是主项目(汽车)的一个分支。
如果将该分支合并进主项目,那么最终的颜色就是红色;如果不合并,则继续使用橄榄绿。
是否将某个贡献者的分支合并进主分支,通常由项目负责人决定。
## 举个例子
Alice 在开发功能 A,Bob 在开发功能 B。
Alice 完成功能 A 一半后,提交了几次;但功能 A 实在太复杂,于是她决定先去开发功能 C,并继续在同一分支(alice)提交。
与此同时,Bob 完成功能 B 后,打算接手功能 A,于是他把 alice 分支合并到了自己的 bob 分支中。
等 Bob 完成功能 A 后,准备将 bob 分支合并进 master。
但 bob 分支此时包含了功能 A、功能 B 和部分功能 C,而功能 C 还没完成!
这就很容易在合并时引发混乱的冲突。
解决办法是:不要用“人名分支”,而应该使用“功能分支”。
Alice 应该为功能 A 和功能 C 分别创建分支;Bob 应该为功能 B 和功能 A 分别创建分支。
这样,他们就能并行开发各自的功能,互不干扰。
## 如何创建分支?
#### 创建分支
```
git branch 任意分支名
```
这将新建一个名为“任意分支名”的分支。
在这个分支上进行的更改不会影响主分支。
详细教程请参考: [如何创建分支](https://www.atlassian.com/git/tutorials/using-branches)
#### 删除分支
```
git branch -d 任意分支名
```
此命令会从 Git 仓库中删除名为“任意分支名”的分支。
参考: [如何从仓库中移除分支](https://github.com/jashnimje/first-contributions/blob/7dcae72208e4b42fcf834b4f189fa8ee78238077/additional-material/git_workflow_scenarios/removing-branch-from-your-repository.md)