Một yêu cầu kéo là gì?

P { margin-bottom: 0.21cm; }CODE.western { font-family: "DejaVu Sans",monospace; }CODE.cjk { font-family: "WenQuanYi Micro Hei",monospace; }CODE.ctl { font-family: "Lohit Hindi",monospace; }A:link { }

What is a pull request?

by Mark Johnson on 0 , last up-dated 8 November 2013

Theo: http://oss-watch.ac.uk/resources/pullrequest

Bài được đưa lên Internet ngày: 08/11/2013

Lời người dịch: Khi một lập trình viên làm việc với một dự án phần mềm nguồn mở, bạn sẽ cần tới việc đệ trình mã cho dự án ngược lên dòng trên và có thể vì thế sẽ nảy sinh ra một yêu cầu kéo (pull request) đối với việc thu nạp mã của bạn vào dự án ngược lên dòng trên đó. Bài này sẽ giải thích tỉ mỉ về quá trình đó, đặc biệt nếu bạn làm việc với GitHub.

Một yêu cầu kéo là một phương pháp đệ trình các đóng góp cho một dự án phát triển mở. Điều này thường là cách được ưu tiên đối với việc đệ trình các đóng góp cho một dự án bằng việc sử dụng một hệ thống kiểm soát phiên bản phân tán - DVCS (version control system) như Git. Một yêu cầu kéo xảy ra khi một lập trình viên yêu cầu những thay đổi được đệ trình tới một kho bên ngoài sẽ được xem xét để đưa vào trong một kho chính của dự án.

Thực hiện một thay đổi

Khi đóng góp cho một dự án nguồn mở bằng việc sử dụng một DVCS, bạn sẽ có một bản sao hoặc “clone” của kho mã nguồn trong môi trường phát triển cục bộ của bạn. Ở đây, bạn có thể thực hiện các thay đổi của bạn và đệ trình chúng một cách cục bộ để tạo ra một lịch sử các sửa đổi, cho phép những thay đổi sẽ được theo dõi và dễ dàng quay ngược lại nếu cần. Các thay đổi được đệ trình một cách cục bộ có thể sau đó được đệ trình cho dự án ngược lên dòng trên để đưa vào trong phát hành tiếp sau.

Một khi người đóng góp thỏa mãn với những thay đổi của họ đáng được xem xét đối với những người duy trì dự án, thì một yêu cầu kéo sẽ phát sinh.

Việc phát sinh một yêu cầu kéo

Phương pháp cho việc nảy sinh một yêu cầu kéo có thể khác nhau giữa các dự án, nên hãy chắc chắn rằng các dự án được viết tài liệu cho các chi tiết. Tuy nhiên, các dự án sử dụng GitHub sẽ thường sử dụng các công cụ của riêng GitHub cho việc điều khiển các yêu cầu kéo. Một tiến trình công việc chung cho việc đệ trình một yêu cầu kéo với GitHub có thể trông giống như thế này:

1. Tạo/Đăng nhập vào tài khoản GitHub của bạn

2. Đi tới trang cho kho mã mà bạn muốn đóng góp tới (“ngược lên dòng trên”)

3. “Rẽ nhanh” kho (điều này tạo ra một bản sao cho tài khoản

4. GitHub của bạn Tạo một bản sao cục bộ rẽ nhánh của bạn với git clone

5. Tạo một nhánh cục bộ cho những thay đổi của bạn

6. Thực hiện các thay đổi của bạn và đệ trình chúng tới nhánh cục bộ của bạn với git commit, đảm bảo đưa vào một thông điệp mô tả đệ trình

7. Đẩy nhánh đó tới rẽ nhánh GitHub của bạn bằng việc sử dụng git push

8. Đi tới trang cho kho ngược lên dòng trên đi tới thẻ tab các yêu cầu kéo

9. Nháy vào núm “New Pull Request” (Yêu cầu Kéo Mới)

10. Chọn nhánh mà bạn muốn đệ trình, và viết một tóm tắt những gì thay đổi của bạn giải thích những gì nó có ý định làm và cách mà nó được triển khai

Các dự án khác có thể xử trí các yêu cầu kéo ngoài github, ví dụ Moodle quản lý các yêu cầu kéo như các thẻ trong trình theo dõi lỗi Jira. Tuy nhiên, bạn sẽ luôn cần phải đẩy các thay đổi tới một kho có khả năng truy cập công khai cho mã của bạn sẽ truy cập được đối với dự án, nên việc có một tài khoản trên một site như GitHub hoặc Bitbucket là một ý tưởng tốt.

 

A pull request is a method of submitting contributions to an open development project. It is often the preferred way of submitting contributions to a project using a distributed version control system (DVCS) such as Git. A pull request occurs when a developer asks for changes committed to an external repository to be considered for inclusion in a project’s main repository.

It is important to note that “pull requests” are a workflow method, and are not a feature of the version control system itself. This document will provide a simple overview of pull requests and how they are cre-ated, using the Git version control system and GitHub hosting site as examples.

Making a change

When contributing to an open source project using a DVCS, you will have a copy or “clone” of the source code repository in your local development environment. Here, you can make your changes and commit them locally to cre-ate a revision history, allowing changes to be tracked and easily rolled back if required. Changes committed locally can then be submitted to the upstream project for inclusion in the next release.

Once the contributor is satisfied that their changes are worthy of consideration by the project maintainers, a pull request is raised.

Raising a Pull Request

The method for rasing a pull request may differ between projects, so be sure to check the projects documentation for details. However, projects using GitHub will often use GitHub’s own tools for handling pull requests. A common workflow for submitting a pull request with GitHub would look like this:

1. Cre-ate/Log in to your GitHub account

2. Go to the page for the code respository you want to contribute to (the “upstream”)

3. “Fork” the repository (this cre-ates a clone to your GitHub account)

4. Cre-ate a local clone of your fork with git clone

5. Cre-ate a local branch for your changes

6. Make your changes and commit them to your local branch with git commit, ensuring to include a descriptive commit message

7. Push the branch to your GitHub fork using git push

8. Go to the page for the upstream repository go to the pull requests tab

9. Click the “New Pull Request” Button

10. Se-lect the branch you want to submit, and write a summary of what your change explaining what it is intended to do and how it is implemented

Other projects may handle pull requests outside of github, for example Moodle manages pull requests as tickets in its Jira bug tracker. However, you’ll always need to push your changes to a publically accessible repository for your code to be accessible by the project, so having an account on a site like GitHub or Bitbucket is a good idea.

Áp dụng một yêu cầu kéo

Một khi một yêu cầu kéo đã được một người đóng góp đệ trình, thì nó sau đó là trách nhiệm của những người duy trì dự án để đánh giá và, ở những nơi phù hợp, trộn nó vào trong kho ngược lên dòng trên. Các dự án khác nhau có các tiếp cận khác nhau đối với việc rà soát lại và áp dụng các yêu cầu kéo. Tuy nhiên, chúng tất cả có một số bước chung:

• Nhanh chóng đánh giá giá trị của những thay đổi

• Chuẩn bị nhắc và ý kiến phản hồi chính xác cho người đóng góp (yêu cầu một sự đệ trình lại ở những nơi phù hợp)

• Kiểm tra mã được thay đổi và chạy bất kỳ bộ kiểm thử nào đối với nó

• Báo cáo bất kỳ vấn đề gì cho người đóng góp và yêu cầu một sự đệ trình lại

• Kéo các thay đổi đó vào mã ngược lên dòng trên

Các lập trình viên có kỹ năng có thể đọc ác khác biệt (các trình bày văn bản của các thay đổi được thực hiện) và hiểu các tác động của chúng mà không thực sự áp dụng chúng cho kho mã. GitHub đưa ra một kiểu nhìn các khác biệt bằng việc mô tả từng yêu cầu kéo để tiến hành điều này dễ hơn.

 

Applying a Pull Request

Once a pull request has been submitted by a contributor, it is then the responsibility of the project maintainers to evaluate and, whe-re appropriate, merge it into the upstream respository. Different projects have different approaches to reviewing and applying pull requests. However, they all have some common steps:

• Quickly evaluate the value of the changes

• Prepare prompt and accurate feedback to the contributor (requesting a resubmission whe-re appropriate)

• Check out the changed code and run any test suites against it

• Report any problems to the contributor and request a resubmission

• Pull the changes into the upstream code

Skilled developers can read diffs (textual representations of the changes made) and understand their implications without actually applying them to the code base. GitHub provides a view of the diff describing each pull request to make this easier. This makes it easy to provide rapid feedback to the contributor. Should the project maintainer feel that the change looks like a solid contribution, they will check out the branch for which the pull is being requested to their local development environment and test it. Since a good contribution will already have undergone extensive testing, this should be a simple matter for the maintainer. However, mistakes can be made and so further testing should always be carried out.

Once a pull request has been approved the maintainer will pull it into the requested branch of the upstream repository, either using GitHub, a git merge or git pull command. This will make the code available in the public version on the upstream repository. If this change is assocaited with an ticket in the issue tracker, the ticket should then be up-dated. GitHub allows this to happen automatically by referencing the issue in the commit message.

Điều này làm cho nó dễ dàng cung cấp các ý kiến phản hồi nhanh cho người đóng góp. Người duy trì dự án nếu cảm thấy rằng thay đổi đó trông giống như một đóng góp cứng cỏi, họ sẽ kiểm tra nhánh theo đó sự kéo đang được yêu cầu cho môi trường phát triển cục bộ của chúng và kiểm thử nó. Vì một sự đóng góp tốt sẽ đi qua rồi việc kiểm thử tăng cường, điều này nên là một vấn đề đơn giản cho người duy trì. Tuy nhiên, các sai sót có thể được thực hiện và vì thế việc kiểm thử tiếp sau nên luôn được triển khai.

Một khi một yêu cầu kéo từng được phê chuẩn thì người duy trì sẽ kéo nó vào nhánh được yêu cầu của kho ngược lên dòng trên, hoặc bằng việc sử dụng GitHub, một lệnh git merge hoặc git pull. Điều này sẽ làm cho mã sẵn sàng trong phiên bản công khai trong kho ngược lên dòng trên. Nếu sự thay đổi này có liên quan tới một thẻ (ticket) trong trình theo dõi vấn đề, thì thẻ đó sau đó sẽ được cập nhật. GitHub cho phép điều này xảy ra một cách tự động bằng việc tham chiếu vấn đề đó trong một thông điệp đệ trình.

Điều đó có thực sự đơn giản?

Điều quan trọng rằng những thay đổi được thực hiện đối với phiên bản mới nhất của mã trong sự phát triển. Trong git, điều này thường là nhánh được gọi là “master” (chủ). Nếu có các phiên bản ổn định vẫn nhận được các bản sửa lỗi và cập nhật, thì bạn có thể muốn xem xét liệu bạn có nên cũng đệ trình một yêu cầu kéo cho những thay đổi cả bạn đối với các phiên bản đó hay không, chúng sẽ thường có các nhánh riêng của chúng trong kiểm soát phiên bản ngược lên dòng trên. Nếu những thay đổi đó sửa một lỗi mà chỉ xảy ra trong một phiên bản cũ hơn, thì sau đó có thể là phù hợp để chỉ đệ trình một yêu cầu kéo đố với phiên bản cũ hơn đó.

Cũng quan trọng là người đóng góp đảm bảo rằng những thay đổi được thực hiện tuân thủ với bất kỳ sự làm tài liệu và các tiêu chuẩn viết mã nào được dự án áp dụng. Cũng là sống còn để kiểm thử kỹ những thay đổi đối với bất kỳ bộ kiểm thử nào mà dự án đưa ra. Cuối cùng, từng đóng góp nên được viết thành tài liệu rõ rằng với ít nhất các chi tiết về:

• Nó có ý định làm gì

• Nó được triển khai thến nào

• Nó được sử dụng thế nào

Để biết thêm về phân tích lý lẽ đằng sau điều này và tầm quan trọng của việc đệ trình các thay đổi của bạn ngược lên dòng trên, hãy đọc các phần Điều đó có thực sự đơn giản? và Vì sao tôi nên đóng góp một bản vá?

Đọc thêm

Các liên kết:

• Trợ giúp của GitHub - Rẽ nhánh một kho

• Trợ giúp của GitHub - Sử dụng các yêu cầu kéo

• Quy trình phát triển của Moodle

Thông tin liên quan từ OSS Watch:

• Quản lý phát hành trong các dự án phần mềm nguồn mở

• Các thỏa thuận giấy phép của người đóng góp

• Kiểm soát phiên bản là gì? Vì sao sự cần mẫn siêng năm là quan trọng?

• Bạn có thể đóng góp mã cho một dự án nguồn mở?

• Làm thế nào để xây dựng một cộng đồng nguồn mở

• Các vai trò trong các dự án nguồn mở

• Bản vá phần mềm là gì?

Is it really that simple?

It is important that changes are made against the latest version of the code in development. In git, this is usually the branch called “master”. If there are stable releases still receiving bug fixes and up-dates, you may want to consider whether you should also submit a pull request for your changes against those versions, which will often have their own branches in the upstream version control. If the changes fix a bug which only occurs in an older version, then it may be appropriate to only submit a pull request against the older version.

It is also important that the contributor ensures that the changes made comply with any documentation and coding standards adopted by the project. It is also critical to thoroughly test changes against any test suites the project provides. Finally, each contribution should be clearly documented with, at a minimum, details on:

• What it is intended to do

• How it is implemented

• How it is used

For more about the rationale behind this and the importance of submitting your changes upstream, read the Is It Really That Simple? and Why Should I Contribute A Patch? sections of our breifing, What is a Software Patch?

Further reading

Links:

• GitHub help - Fork a Repo

• GitHub help - Using Pull Requests

• Moodle Development Process

Related information f-rom OSS Watch:

• Release management in open source software projects

• Contributor Licence Agreements

• What is version control? Why is it important for due diligence?

• Can you contribute code to an open source project?

• How to build an open source community

• Roles in open source projects

• What is a Software Patch?

Dịch: Lê Trung Nghĩa

letrungnghia.foss@gmail.com