我对一流拉取请求的定义

最新推荐文章于 2022-01-27 09:37:09 发布

weixin_26749889

最新推荐文章于 2022-01-27 09:37:09 发布

阅读量236

点赞数

文章标签： java python

原文链接：https://medium.com/dropoutlabs/my-definition-of-a-first-class-pull-request-96094994e67d

版权

Over the years, I have worked on a few projects where I was the sole developer. Being a sole developer has its challenges since not everyone reviewing your pull requests (or merge requests for the Gitlab folks) has an understanding of the repository like I do. Because of this, I like to give a bit more context to every pull request I create so reviewers know what to expect when reviewing code.

多年来，我曾在几个项目中担任过唯一的开发人员。作为唯一的开发人员面临着挑战，因为并不是每个人都像我一样了解存储库，因此，并非每个审阅您的拉取请求(或对Gitlab人员的合并请求)的人都对存储库有所了解。因此，我想为我创建的每个拉取请求提供更多上下文，以便审阅者知道审阅代码时的期望。

In this post, I am primarily focusing on pull requests regarding front end development and working on SaaS software, but this format could work for others too. My typical pull request is broken into four main sections: context, testing, checklist items, and then any related GitHub issues or JIRA tickets that will be closed as a result of the merge.

在本文中，我主要关注有关前端开发和使用SaaS软件的请求请求，但是这种格式也适用于其他人。我的典型拉取请求分为四个主要部分：上下文，测试，清单项目，然后是合并后将关闭的任何相关GitHub问题或JIRA票证。

I like small, concise code changes as much as the next developer, but it’s not always feasible. Features may span hundreds of lines and have corresponding tests. Having worked with both backend and front end code, the front end, more often than not, contains substantially more modifications at a time.

我喜欢下一个开发人员那样小的，简洁的代码更改，但这并不总是可行的。特征可能跨越数百条线并具有相应的测试。在使用了后端代码和前端代码之后，前端通常一次包含更多的修改。

语境 (Context)

Having context around a pull request is the most important part, aside from the code itself, of course. The dictionary defines context as:

当然，除了代码本身之外，在拉取请求周围具有上下文是最重要的部分。字典将上下文定义为：

the circumstances that form the setting for an event, statement, or idea, and in terms of which it can be fully understood

构成事件，陈述或想法的设置的环境，并且可以据以充分理解

With that in mind, we want anyone who is reading the pull request to have an understanding of what the pull request is about before looking at the code. Yes, your code may be declarative and easy to read with or without comments, but it may not be coherent to the reviewer.

考虑到这一点，我们希望正在阅读拉取请求的任何人在查看代码之前先了解拉取请求的含义。是的，您的代码可能是声明性的，易于阅读，带有或不带有注释，但对于审阅者而言可能不一致。

When opening a pull request, ask yourself these questions:

打开请求请求时，请问自己以下问题：

What is the purpose of this pull request? Is this a bug fix? New feature? Documentation update? Refactor?
此请求请求的目的是什么？这是一个错误修复程序吗？新功能？文档更新？重构？
How do these changes solve a particular problem?
这些更改如何解决特定问题？
Is there any context outside this pull request that should be surfaced?
除此拉取请求之外，是否应该显示其他上下文？

These questions can help both you and the reviewer set expectations around what has been changed.

这些问题可以帮助您和审阅者对已更改的内容设定期望。

意象 (Imagery)

Imagery is one category that I think doesn’t get enough attention. If an image is worth a thousand words, why not include one? Instead of putting together a pull request where you changed the button colour to red and describing it as so, why not add an image of the red button? You will likely save yourself time and the reviewer will now have a visual aid.

我认为图像是一类没有引起足够重视的类别。如果一张图像值一千个单词，为什么不包含一个呢？为何不添加将按钮颜色更改为红色并以此描述的拉取请求，为什么不添加红色按钮的图像呢？您可能会节省时间，并且审阅者现在将获得视觉帮助。

An example screenshot which represents a small area of a user interface. In this instance, when a user enables the redact on row level option, single row level redactions can be added to a policy.

屏幕截图示例代表了用户界面的一小部分。在这种情况下，当用户启用行级别上的修订选项时，可以将单行级别的修订添加到策略中。

After implementing a new feature that performs a series of steps, it can be helpful to include a short GIF of it in action. Use any screen recording tools available to your operating system. On macOS, I like to use CleanShot to record an area of my screen. CleanShot is paid software, but there are other free alternatives like QuickTime or open-source like Kap.

在实现执行一系列步骤的新功能之后，将简短的GIF包含在操作中可能会有所帮助。使用操作系统可用的任何屏幕录制工具。在macOS上，我喜欢使用CleanShot记录屏幕区域。 CleanShot是付费软件，但是还有其他免费替代软件，如QuickTime或开源软件如Kap 。

An example GIF displaying a series of steps a user might take while interacting with a feature. In this instance, a user is interacting with a series of checkboxes and verifying an option to select all works as expected.

测试中 (Testing)

You can refer to this section as defining the steps needed to verify the changeset works as expected. Manually testing may not be required all the time, but it’s a good way to catch errors that you didn’t encounter. When something should be verified by the reviewer, define the individual steps they should take.

您可以参考本节，以定义验证变更集是否按预期工作所需的步骤。可能并非一直都需要手动测试，但这是捕获未遇到的错误的好方法。当审阅者应验证某件事时，请定义他们应采取的各个步骤。

Before writing down the steps, include any details around things needed to be present before a successful test can take place. This may involve having additional users seeded in the database, tools required and configured a certain way, or performing an action beforehand.

在写下步骤之前，请包含成功进行测试之前需要呈现的所有细节。这可能涉及到在数据库中植入其他用户，以某种方式配置所需的工具或预先执行操作。

If a preview environment isn’t available to test on before the changes are merged, consider having a link to the contributing documentation for setting up the local development environment.

如果在合并更改之前无法使用预览环境进行测试，请考虑使用指向提供帮助的文档的链接来设置本地开发环境。

I like to use an unordered or ordered list to keep track of the steps necessary to confirm a feature is working. Here is an arbitrary example of what this might look like:

我喜欢使用无序列表或有序列表来跟踪确认功能正常运行所必需的步骤。这是一个看起来像这样的任意示例：

### Testing
⚠️**NOTE:** To verify this functionality you will need **at least two users** within the database ⚠️
1. Navigate to the home screen
2. Click the  **Add/edit users** button
3. Verify a modal appeared and lists X users
4. Click the **(+ add user)** button next to user one
5. Verify the **(+ add user)** button has turned to an **(x remove user)** and the user has been added
6. Click the **(x remove user)** button
7. Verify the user has been removed

I conventionally follow a pattern of performing an action and then verifying it worked. You can jot down these steps with the same mentality as you would approach end-to-end tests.

我通常遵循一种执行动作，然后验证其是否有效的模式。您可以按照进行端到端测试的相同思路来记下这些步骤。

Try to keep the steps small and concise so the reviewer can follow along without much effort. It’s more feasible for them to reach out to you with any questions regarding step X versus describing a step in the middle of a paragraph.

尝试使步骤小而简明，以便审阅者可以毫不费力地遵循。对于他们而言，与有关段落X的任何问题相提并论而不是在段落的中间描述步骤，对他们来说更可行。

检查清单 (Checklist)

Are there items that need to be verified and can’t be automated for each pull request? Include a checklist of criteria that must be true before it can be merged.

是否存在需要验证且无法针对每个提取请求自动执行的项目？包括一个标准清单，该清单必须为真，然后才能合并。

Many of these action items are not so much for the reviewer, but for you, the author. These items might include:

这些操作项中的许多内容对于审阅者而言并不重要，对您而言，对于作者而言。这些项目可能包括：

- I have added tests to prove my fix is effective or that my feature works
- I have added the necessary documentation (if appropriate)
- I have tested this feature in: 	
	- Google Chrome
	- Safari
	- Firefox
	- Internet Explorer
	- Edge
- I have performed a self-review of my code
- I have followed the CONTRIBUTING guidelines

拉取请求模板 (The Pull Request Template)

Pull request templates allow all contributors to follow a similar standard. Both GitHub and GitLab give you the option to include one within your repository.

拉取请求模板允许所有贡献者遵循类似的标准。 GitHub和GitLab都允许您选择在存储库中包含一个。

On GitHub, you can place a file named PULL_REQUEST_TEMPLATEin the root directory of the repository. If you want to keep these files out of the root, you can place it within a .github folder with the file suffix, PULL_REQUEST_TEMPLATE.md.

在GitHub上，您可以将一个名为PULL_REQUEST_TEMPLATE的文件PULL_REQUEST_TEMPLATE在存储库的根目录中。如果要将这些文件保留在根目录之外，则可以将其放在带有文件后缀PULL_REQUEST_TEMPLATE.md的.github文件夹中。

Here is an example you can use to get started:

这是您可以开始使用的示例：

### Context
- What is the purpose of this pull request? Is this a bug fix? New feature? Documentation update? Refactor?
- How do these changes solve a particular problem?
- Is there any context outside of this pull request that should be surfaced?
#### Imagery
If you're changing the UX behaviour, include a screenshot or GIF of your changes.
### Testing
As an end-user, how can I manually verify this code is working as expected? List out all steps required
### Checklist
Before submitting your pull request, please review the following checklist. __Put an `x` in the boxes that apply.__
- [ ] I have added tests to prove my fix is effective or that my feature works
- [ ] I have added the necessary documentation (if appropriate)
- I have tested this feature in: 	
	- [ ] Google Chrome
	- [ ] Safari
	- [ ] Firefox
	- [ ] Internet Explorer
	- [ ] Edge
- [ ] I have performed a self-review of my code
- [ ] I have followed the [CONTRIBUTING](/CONTRIBUTING.md) guidelines
### Related issues or pull requests
closes N/A

Modify this template to fit your needs or check awesome-github-templates for more examples.

修改此模板以满足您的需求，或者查看awesome-github-templates以获取更多示例。

I hope this article gave you some ideas of your own on how you can help improve the quality of you and your teammates pull requests. Everyone can benefit from the additional context, imagery and testing steps on every pull request. Besides, what’s a couple of minutes to look like a pull request superstar?

我希望本文能给您一些自己的想法，以帮助您提高自己和队友提出请求的质量。每个拉动请求中的每个人都可以从附加的上下文，图像和测试步骤中受益。此外，看起来像请求请求的超级巨星还有几分钟？

关于海角隐私 (About Cape Privacy)

Cape Privacy is an enterprise SaaS privacy platform for collaborative machine learning and data science. It helps companies maximize the value of their data by providing an easy-to-use collaboration layer on top of advanced privacy and security technology, helping enterprises increase the breadth of data included in machine learning models. Cape Privacy’s platform is flexible, adaptable, and open source. It helps build trust over time providing for seamless collaboration and compliance across an organization or multiple businesses. The company is based in New York City and is backed by boldstart ventures and Version One with participation from Haystack, Radical, and Faktory Ventures.

Cape Privacy是用于协作式机器学习和数据科学的企业SaaS隐私平台。 它通过在高级隐私和安全技术之上提供易于使用的协作层，帮助企业最大程度地提高数据价值，从而帮助企业提高机器学习模型中包含的数据的范围。 Cape Privacy 的平台是灵活，适应性强且开源的。 随着时间的推移，它有助于建立信任关系，从而在整个组织或多个业务中实现无缝协作和合规性。 该公司总部位于纽约市，并获得了大胆创业公司和Version One的支持，并获得了Haystack，Radical和Faktory Ventures的参与。