What
is a pull request?
by Mark Johnson
on 0 , last updated 8 November 2013
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:
- Tạo/Đăng nhập vào tài khoản GitHub của bạn
- Đ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”)
- “Rẽ nhanh” kho (điều này tạo ra một bản sao cho tài khoản
- 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
- Tạo một nhánh cục bộ cho những thay đổi của bạn
- 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
- Đẩy nhánh đó tới rẽ nhánh GitHub của bạn bằng việc sử dụng git push
- Đ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
- Nháy vào núm “New Pull Request” (Yêu cầu Kéo Mới)
- 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 created, using the Git version control system and GitHub
hosting site as examples.
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 create 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.
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:
- Create/Log in to your GitHub account
- Go to the page for the code respository you want to contribute to (the “upstream”)
- “Fork” the repository (this creates a clone to your GitHub account)
- Create a local clone of your fork with
git clone - Create a local branch for your changes
- Make your changes and commit them to your local branch with
git commit, ensuring to include a descriptive commit message - Push the branch to your GitHub fork using
git push - Go to the page for the upstream repository go to the pull requests tab
- Click the “New Pull Request” Button
- Select 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.
Once
a pull request has been submitted by a contributor, it is then the
responsibility of the project maintainers to evaluate and, where
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 where 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 updated. 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:
Thông tin liên quan từ
OSS Watch:
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 updates, 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?
Links:
Related
information from OSS Watch:
Dịch: Lê Trung Nghĩa
Không có nhận xét nào:
Đăng nhận xét
Lưu ý: Chỉ thành viên của blog này mới được đăng nhận xét.