今日推荐开源项目：《简单方便实惠 notable》
今日推荐英文原文：《The Art of a Well Composed Pull Request》
今日推荐开源项目：《简单方便实惠 notable》传送门：GitHub链接
推荐理由：这世界上没有一个具有如下特点的 Markdown app： GitHub 风格，没有 WYSIWYG（尽管这在某些时候很方便），没有专用格式，支持附件，允许导入等等。所以我就自己造了一个。——作者
如果没有就自己做一个适合自己的 app，这个思想是相当好的，自己动手不仅能满足需求还能学到东西何乐而不为呢？
今日推荐英文原文：《The Art of a Well Composed Pull Request》作者：Zoe Larsen
原文链接：https://medium.com/@zlarsen.zl/the-art-of-a-well-composed-pull-request-3815fc7e9610
推荐理由：Pull Request 的艺术
The Art of a Well Composed Pull Request
What is a Pull Request?
A pull request (PR) is a request submitted to a GitHub repository to merge code into that project. The PR allows requested reviewers to view and discuss the proposed code. Once the PR passes all standards of reviews and all necessary revisions have been made, it can be merged into the code base.
To get an in depth overview of git and how to make commits, PRs, and repositories; here is a great guide to get you started: git — the simple guide
The purpose of this article is to present good practices for how to piece together a PR that is clear, easy to review, and inherently self-documenting.
Why are Pull Requests Important?
Pull requests are important because they help ensure that quality reviewed code is merged into GitHub repositories. Without PRs, messy and confusing code can easily run rampant in a code base. Each developers’ style of programming will compound into a repository with wildly different standards of code. This creates a confusing repository that is difficult to decipher for new developers or even the same developers six month later. PRs are a gate keeping tool to prevent bad or malicious code from being merged into the code base.
Even with this tool, it does not prevent developers from making bad PRs. Especially if there are time restraints, a complex set of commits, or a myriad of other excuses, it’s easy to lump all code changes into a single commit and push it up the repository. However, that is a terrible PR for other developers to review. A bad PR with sparse description and no forethought for how it’s structured can waste multiple developers time.
Concise pull requests allow for developers to efficiently review and quickly merge code into master. Mastering the art of a well composed PR will make you a valuable asset to any developer team.
Pull Requests are Made of Commits
A pull requests is made of a number of committed code changes. The developer then pushes the commits to a repository on github. It’s important to organize commits in a coherent manner to best convey what changes were made to the code made with each commit.
I personally try to organize my commits with some sort of flow in mind. I think it’s important to have some sort of story that helps make the abstraction of coding into something that easier to read through and understand. Here are several ways to organize commits
+ MCV flow: commit changes made to the model first, then followed by changes made to the controllers, finally changes made to the views. + Importance flow: Commit changes that are the most important first then commit associated minor changes. + Biggest to smallest flow: Commit changes that were the biggest changes to the code, followed by more minor changes.
These are just a few suggestions, there may be better ways to organize your commits that make the most sense to your team. The most important takeaway is to put some thought into it.
Thus when the commits are pushed to the GitHub repository and the pull request is made, it is easy for a PR reviewer to go through each commit and understand the thought process that necessitated the changes made in each commit.
I try to keep commit messages as concise as possible and limit the code changes to a single idea or step.
A useful git function for organizing commits is rewriting commit history.
Commit Tips
I structure my commit messages the following way
+ Title summing up the code changes I made in the present tense. + Message of why I made those changes.
Change variable name foo_bar to foo_bars
Renamed the variable foo_bar to foo_bars across all files that had that variable. Renaming this variable better conveyed that the variable was an array of strings instead of a single value.
I avoid commits that have a ton of changes across many different files unless they are all a similar change.
For example, If I made changes to a user controller file, a product subscription helper file, and product view file I would make three commits for the changes I made in each file.
Another example, if I made changes to ten view files that just changed the same variable name to a new variable then I would add all ten files to one commit.
Finally before you push up all your commits and are ready to open a new pull request, do everyone a favor and personally review your code.
Make sure you try to catch as many dumb small mistakes as you can.
Indention off? Fix it.
Variable/function names not very clear? Rename them.
DRY up your code.
You will save yourself and your reviewers time if you catch these hiccups before submitting them for review. Nothing sucks more when the senior developer comments that you misspelled organism_name as orgasm_name.
Usually I’ll commit these small changes and fixes as a personal PR review.
A Well Composed PR
Now that we have some well structure commits we can now push our changes to the GitHub repository and open a brand new PR. Composing a PR is similar to composing a commit, except it encompasses the whole purpose of the code changes instead of the small changes made to each file or feature.
PR Title
I sum up the general purpose of the PR being made in the title as concisely as I can manage. I typically have the general goal of the PR followed by the area and function
For Example:
+ New Design Bug Fix: User Controller Index Action. + System Test: React Tables Basic Functionality. + Model Bug Fix: Permission Class Method Update.
PR Body
For the PR Body Message I break it up into several sections.
+ Purpose of PR/What Issue it is Resolving + Main Changes made + Code Before Changes/Code After Changes + Additional media resources (Images, links to other PRs/Issues)
I also include other media sources if they are relevant to help explain the changes made. Things like before/after images for view changes, gifs to show functionality changes, or other media assets would be great to help illustrate what happened in the PR that affected the code base.
Additionally, I link any issues or other PR’s that are associated with the current PR being reviewed. This is especially helpful for the future when, for whatever reason, you or another developer have to look back on the changes you made.
You might have to figure out why such vague variable names were assigned, why such hacky code was implemented, or a myriad of other things that make sense now but won’t in a few months when you have completely forgotten about this pull request.
Having as much contextual information associated with the PR is extremely helpful for future developers.
The PR Conversation
Finally once you have crafted a fine PR and submitted it for review, the work is not over yet. The developers reviewing your PR will no doubt make comments on your code to clarify something or ask you to make revisions. This will start the conversation in your PR review.
I find that it is important to respond to every comment made on your PR with either a thumbs up emoji to acknowledge that you made small changes requested and with another comment if you need to explain something. Including images in your comment response when necessary is also a great way to help clarify your response.
下载开源日报APP：https://openingsource.org/2579/
加入我们：https://openingsource.org/about/join/
关注我们：https://openingsource.org/about/love/
