document/TranslateProject
2
0
Fork 0
mirror of https://github.com/LCTT/TranslateProject.git synced 2024-12-26 21:30:55 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #28466 from ZhangZhanhaoxiang/20221228.1-⭐️⭐️-11-tips-for-writing-a-good-Git-commit-message.md

Browse Source 
translated
This commit is contained in:
Xingyu.Wang 2023-01-21 10:49:27 +08:00 committed by GitHub
commit 604a33c2e5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 185 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
sources/tech/20221228.1 ⭐️⭐️ 11 tips for writing a good Git commit message.md
View File

@ -1,185 +0,0 @@
[#]: subject: "11 tips for writing a good Git commit message"
[#]: via: "https://opensource.com/article/22/12/git-commit-message"
[#]: author: "AmyJune Hineline https://opensource.com/users/amyjune"
[#]: collector: "lkxed"
[#]: translator: " "
[#]: reviewer: " "
[#]: publisher: " "
[#]: url: " "
11 tips for writing a good Git commit message
======
Lately, I have been paying closer attention to the changelogs I get from products and services when updates are needed. Here are some examples:
- Fixed some bugs.
- Made some accessibility improvements.
- We've made improvements and fixed bugs for a smoother ride.
When I think about some of the first commit messages I made as a junior developer I have to hang my head in dismay:
- Pointed and clicked around a bit and now things seem to work.
- Did what programmer X told me to do and now the banner is blue.
This can be frustrating! I asked our community of contributors the following questions:
- What makes a good Git commit message?
- What makes a bad one?
- What rules do you think a project should have around what a commit message contains?
Here are their answers:
### Great writing is key
As with anything you write, you should think about who is going to read it. Then adapt the amount and depth of information accordingly.
Improving your natural language and writing skills is essential for a healthy career in software development. It's not just code that counts.
**—[Camilla Conte][1]**
### Be descriptive and don't assume
I spend a lot of my time collaborating in the [OpenStack][2] community, and its code reviewers have some fairly exacting standards compared to what I see from other projects "in the wild."
I'll often spend far longer composing a solid commit message than I do writing the actual code implementation or fix. Sometimes commit messages can end up many times longer than the diffs they're explaining.
To summarize some of the contributor guidance:
- Describe why a change is being made, not just what is changing
- The first commit line is the most important (like the subject line of an email)
- Don't assume reviewers understand the original problem you're fixing
- Don't assume the reviewer has access to external web services or the site (summarize defect reports and other relevant discussions)
- Don't assume the code is self-evident and self-documenting (though there is no need to repeat points you also make in your code comments)
- Don't include information only relevant to earlier revisions of the change (we expect contributors to squash revisions together and edit their commit messages accordingly).
There's a brief section on the topic in the OpenStack Contributors Guide: [https://docs.openstack.org/contributors/common/git.html#commit-messages][3]
**—[Jeremy Stanley][4]**
### Your future self will thank you
I cannot agree more with Jeremy. +1000
Jeremy said, "describe why a change is being made, not just what's changing."
Imagine you're someone else, in a faraway future, trying to work out this commit.
Put yourself in other people's shoes, as the old saying goes.
**—[Leigh Morresi][5]**
### Use the bug ID
I recommend adding the bug ID at the start of the commit message so that it's easier to track the commits at a later stage using the [`grep` command][6].
For example:
```
$ git commit -m "BZ#19xxxxx
```
To come up with thoughtful commits, consider the following:
- Why have I made these changes?
- What effect have my changes made?
- Why was the change needed?
- What are the changes in reference to?
**—[Agil Antony][7]**
### Tell the whole story
I like to imagine there is a hidden prefix to every commit message that reads "By applying this."
A good commit message includes exactly what will happen and why. It is insufficient to merely have the work ticket reference because that decentralizes the information; Git is decentralized. As a software developer, I want to know why the proposed changes are being considered. What specific problem is being addressed? What alternate solutions were considered (and discarded)? What unexpected things were discovered during the creation of the changeset that influenced the current content?
There's no prize for shortest commit message. Your future self and future colleagues will appreciate you going into depth to explain the problem and why this changeset is the answer. Harness those cooking blogs where there's a five-paragraph life story. Here, however, make the problem the subject of the life story.
**—[Lisa Seelye][8]**
### But don't be overly verbose
A good git commit message contains information about what was done, and nothing else. For instance, if you needed to update the .gitignore, just say "updated .gitignore." Folks can dive into the commit itself for more details. It doesn't need to be verbose.
A bad commit message is something like, "oh crap" or "try this". Granted, I've been guilty of this, but it doesn't help anyone if they need to look at commits at a glance.
Rules are very subjective. They can differ from lead to lead and team to team. But at the very least, give some contextual information about the commit. Especially if it's a large one. No one has time to skim through 1000+ files with a heavy change history.
**—[Miriam Goldman][9]**
### Use present tense
I like project manager-styled commit messages written in present and not future terms (for example, "add" instead of "added"). However, it's usually only possible if commits are frequent. There's only so much "how did I do it" you can remember when you're faced with a deadline. Yet, well-written commits not only help collaborators, but are also helpful to the committer in recollecting history.
**—[Chris Okpada][10]**
### Don't rely on links
One thing I like to remind colleagues of is that you're not just explaining to the people who are going to decide whether to approve your commit. You're also explaining to future developers and users who have found this commit in a bisect or blame operation and are trying to understand its relevance.
If the only context supplied is a link to some external system, and that far in the future the system it links to is no longer in use or has otherwise become inaccessible to that individual, your commit message has been rendered useless and may just as well be blank.
All too often, I go digging in the Git history of some open source project, and find commit messages which are nothing more than a bug ID or a link to some company's internal and private defect tracker.
Don't be that project!
**—[Jeremy Stanley][4]**
### Clear and concise changelogs
As a release communications manager, I often read the entire release board. I also met with developers to discuss any areas that weren't clear yet. Then I tested the release early. After that, I would write a release post by sourcing the changelogs and corresponding revised or new content.
The changelogs are personal reminders for developers, but also have corresponding issues and tickets for them. You should capitalize product names appropriately, use a spell checker, be consistent with punctuation, and sentence structure. The lead developer should proofread these as well. Your customers, that are developers, are reading these. What information should they know before running the update to better serve their customers?
**—[Courtney Robertson][11]**
### Be specific
As a frequent release manager, I like messages that name the component a commit touches, and a brief description of what was changed. Also having a reference back to where the request for this work came from helps to tie fixes together long after we forgot about your clever branch name.
- "fix fatal error" is not ideal.
- "ISS-304: Fix fatal error in Login Access Control function for users
with the Partner role" is better.
- "ISS-304: Login Access Control: fix fatal error in getPartnerId()" is
better still.
I can look at the entire relationship between a Git commit, branch, merge commit, and inspect the individual lines and files that were changed. But I don't have that kind of time in the middle of a release. I want to be able to relate back to the source of this work in the project management tool, have some idea of which components are being changed, and in what way.
**—[Ryan Price][12]**
### Make it a habit
My favorite commit that I'm guilty of is, "commit before I switch branches" because I have to work on something else more urgent. Sometimes, I need to commit my current work to a totally different project. My manager's strategy is to have us work as we normally do. But then when we rebase, he wants us to squash commits where it makes sense and write better messages. I can't say we always do this, but his method does make sense.
I have a lot of "this is broken don't know why" type messages too (haha) where I try things but want to commit that attempt before I try something else in case method A was closer to fixing the issue than method B. Writing code is a hot mess. And I've been writing it for over 10 years.
**—[RachieVee][13]**
What commit message advice or tips do you live by? Let us know in the comments.
--------------------------------------------------------------------------------
via: https://opensource.com/article/22/12/git-commit-message
作者：[AmyJune Hineline][a]
选题：[lkxed][b]
译者：[译者ID](https://github.com/译者ID)
校对：[校对者ID](https://github.com/校对者ID)
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
[a]: https://opensource.com/users/amyjune
[b]: https://github.com/lkxed
[1]: https://opensource.com/users/spotlesstofu
[2]: https://opensource.com/resources/what-is-openstack
[3]: https://docs.openstack.org/contributors/common/git.html#commit-messages
[4]: https://opensource.com/users/fungi
[5]: https://opensource.com/users/dgtlmoon
[6]: https://opensource.com/downloads/grep-cheat-sheet
[7]: https://opensource.com/users/agantony
[8]: https://opensource.com/users/lisa
[9]: https://opensource.com/users/miriamgoldman
[10]: https://opensource.com/users/ojchris
[11]: https://opensource.com/users/courtneyrdev
[12]: https://opensource.com/users/liberatr
[13]: https://opensource.com/users/rachievee

185
translated/tech/20221228.1 ⭐️⭐️ 11 tips for writing a good Git commit message.md Normal file
View File

@ -0,0 +1,185 @@
[#]: subject: "11 tips for writing a good Git commit message"
[#]: via: "https://opensource.com/article/22/12/git-commit-message"
[#]: author: "AmyJune Hineline https://opensource.com/users/amyjune"
[#]: collector: "lkxed"
[#]: translator: "ZhangZhanhaoxiang"
[#]: reviewer: " "
[#]: publisher: " "
[#]: url: " "
编写好 Git 提交消息的 11 个技巧
======
最近，当需要更新时，我一直在密切关注从产品和服务获得的变更日志。以下是一些示例：
- 修复了一些错误。
- 进行了一些可访问性改进。
- 我们已经进行了改进并修复了错误，以实现更顺畅地运行。
当我想到我作为一名初级开发人员发出的一些最初的承诺信息时，我不得不沮丧地垂下头：
- 用鼠标点了一下，现在一切似乎都正常了。
- 执行了程序员 X 告诉我的操作，现在横幅是蓝色的。
这可能令人沮丧！我向我们的贡献者群体提出了以下问题：
- 什么是好的 Git 提交消息？
- 什么是坏的 Git 提交消息？
- 你认为一个项目应该有哪些关于提交消息所写内容的规则？
以下是他们的答案：
### 易阅读的文笔是关键
与你写任何东西一样，你应该考虑谁会阅读它。然后相应地调整信息的数量和深度。
提高你的自然语言和写作技能对于软件开发的顺利职业生涯至关重要。重要的不仅仅是代码。
**—[Camilla Conte][1]**
### 具有描述性，不要假设
我花了很多时间在 OpenStack[2] 社区中进行合作，与我在像“野外”一样随意的其他项目中看到的相比，它的代码审查员有一些相当严格的标准。
我撰写一条可靠的提交消息的时间通常要比编写实际的代码实现或修复程序的时间长得多。有时，提交消息所需的时间可能会比它们解释的差异长很多倍。
总结一些贡献者指导：
- 描述为什么要做出改变，而不仅仅是改变了什么
- 第一个提交行是最重要的（就像电子邮件的主题行）
- 不要自认为审查人员了解你正在修复的原始问题
- 不要自认为审查者可以访问外部 web 服务或网站（总结缺陷报告和其他相关讨论）
- 不要假设代码是不言自明的和自我记录的（尽管没有必要重复您在代码注释中也提出的观点）
- 不要只包含与更改的早期修订相关的信息（我们希望贡献者将修订压缩在一起，并相应地编辑其提交消息）。
《OpenStack 贡献者指南》中有一个关于该主题的简短章节：[https://docs.openstack.org/contributors/common/git.html#commit-messages][3]
**—[Jeremy Stanley][4]**
### 你未来的自己会感谢你
我非常同意杰里米的观点。1000 份地支持。
Jeremy 说：“描述为什么要做出改变，而不仅仅是改变了什么。”
想象一下，你是旁观者，在遥远的未来，试图理解这个提交。
正如老话所说，设身处地为他人着想。
**—[Leigh Morresi][5]**
### 使用 bug 的 ID
我建议在提交消息的开头添加 bug ID，以便稍后使用 [`grep` 命令][6] 更容易跟踪提交。
例如：
```
$ git commit -m "BZ#19xxxxx
```
要写出深思熟虑的提交，请考虑以下事项：
- 我为什么要做这些更改？
- 我的更改产生了什么影响？
- 为什么有更改的必要？
- 更改的依据是什么？
**—[Agil Antony][7]**
### 讲述整个故事
我喜欢想象每个提交消息都有一个隐藏的前缀，上面写着“By applying this（通过应用这个）”。
一个好的提交消息包括将要发生的事情以及原因。仅仅有工作任务清单作参考是不够的，因为这分散了信息；Git 是去中心化的。作为一名软件开发人员，我想知道为什么当前要考虑做出更改。正在解决的具体问题是什么？考虑（并放弃）了哪些替代解决方案？在创建变更集的过程中发现了哪些影响当前内容的意外情况？
缩短提交消息没有什么用。你未来的自己和未来的同事会感激你深入解释问题，以及为什么这个变更集是解决方案。认真学习和利用那些有丰富“生活经验”的“烹饪”博客。然而，在此，仅仅是把生活经验替换成了项目的问题罢了（LCTT 译注：意思是要认真学习和模仿优秀、详细的 commit）。
**—[Lisa Seelye][8]**
### 但不要过于冗长
一个好的 git 提交消息包含有关所做操作的信息，而不要包含其他信息。例如，如果您需要更新.gitignore，只需写“updated .gitignore”即可。人们可以自行深入到提交本身中了解更多细节。它不需要冗长。
令人反感的提交消息类似于“哦，废话”或“试试这个”。当然，我对此感到内疚，但这对于任何需要看一眼提交的人来说都没有任何帮助。
提交信息的规则非常主观。他们可能因领导和团队而异。但至少要提供一些有关提交的上下文信息。特别是如果它是一个大的更改。没有人有时间浏览 1000 多个具有重大更改历史的文件。
**—[Miriam Goldman][9]**
### 使用现在时
我喜欢用现在时而不是将来时的术语编写项目经理风格的提交消息（例如，“add”而不是“added”）。然而，这通常只有在频繁提交时才有可能。当你面临最后期限时，你能记住的只有“我是如何做的”而已。然而，写得好的提交不仅有助于合作者，而且有助于提交者回忆历史。
**—[Chris Okpada][10]**
### 不要依赖链接
我想提醒同事的一件事是，你不仅仅是向给你的提交作批准的人解释。你还将向未来的开发人员和用户解释，他们会发现这提交有利有弊，或者指责操作，并试图了解其相关性。
如果提供的唯一的上下文是指向某个外部系统的链接，并且在未来很长一段时间内，它所链接的系统不再使用，或者该用户无法访问，那么您的提交消息将变得无用，也相当于是空白的。
我经常去挖掘一些开源项目的 Git 历史，发现有些提交消息无非就是一个 bug ID，或者是某个公司内部的和专用缺陷跟踪器的链接。
不要依赖链接！
**—[Jeremy Stanley][4]**
### 清晰简洁的变更日志
作为一名发行沟通经理，我经常阅读整个发行版。我还与开发人员会面，讨论任何尚未明确的领域。然后我很早就测试了这个版本。之后，我将通过寻找变更日志和相应的修订或新内容来撰写发布帖子。
变更日志是开发人员的个人提醒，但也有相应的提议和问题。您应该适当地将产品名称大写，使用拼写检查器，与标点符号和句子结构保持一致。首席开发人员也应该校对这些。您的客户，即开发人员，正在阅读这些内容。在运行更新之前，他们应该了解哪些信息能更好地为客户服务？
**—[Courtney Robertson][11]**
### 具体一点
作为一个频繁发布的管理者，我喜欢将组件命名为提交的消息，以及对更改内容的简要描述。在我们忘记了你聪明的分支名称之后，还可以参考一下这项工作的请求来自何处，这有助于将修复程序联系在一起。
- “fix fatal error”并不是理想的提交。
- “ISS-304: Fix fatal error in Login Access Control function for users with the Partner role”更好。
- “ISS-304: Login Access Control: fix fatal error in getPartnerId()”也是更好。
我可以查看 Git 提交、分支、合并提交之间的整个关系，并检查更改的各个行和文件。但我在发布过程中没有这样的时间。我希望能够回到项目管理工具中这项工作的来源，了解哪些组件正在被更改，以及以何种方式进行更改。
**—[Ryan Price][12]**
### 让它成为一种习惯
我最喜欢犯的错误是“在我切换分支之前提交”，因为我必须处理其他更紧急的事情。有时候，我需要把我目前的工作提交给一个完全不同的项目。我的经理的策略是让我们像平时一样工作。但当我们重新启动时，他希望我们在有意义的地方压缩提交，并编写更好的消息。我不能说我们总是这样做，但他的方法确实有道理。
我也有很多“这是坏的，不知道为什么”类型的消息（哈哈），我尝试了一些东西，但想在尝试其他东西之前提交该尝试，以防方法 A 比方法 B 更接近解决问题。我已经写了 10 多年了。
**—[RachieVee][13]**
你生活中的提交信息建议或提示是什么？让我们在评论中知道。
--------------------------------------------------------------------------------
via: https://opensource.com/article/22/12/git-commit-message
作者：[AmyJune Hineline][a]
选题：[lkxed][b]
译者：[ZhangZhanhaoxiang](https://github.com/ZhangZhanhaoxiang)
校对：[校对者ID](https://github.com/校对者ID)
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
[a]: https://opensource.com/users/amyjune
[b]: https://github.com/lkxed
[1]: https://opensource.com/users/spotlesstofu
[2]: https://opensource.com/resources/what-is-openstack
[3]: https://docs.openstack.org/contributors/common/git.html#commit-messages
[4]: https://opensource.com/users/fungi
[5]: https://opensource.com/users/dgtlmoon
[6]: https://opensource.com/downloads/grep-cheat-sheet
[7]: https://opensource.com/users/agantony
[8]: https://opensource.com/users/lisa
[9]: https://opensource.com/users/miriamgoldman
[10]: https://opensource.com/users/ojchris
[11]: https://opensource.com/users/courtneyrdev
[12]: https://opensource.com/users/liberatr
[13]: https://opensource.com/users/rachievee