Pull request'y on GitHub or How do I make changes to someone else's project
At the request of tulskiy, I do a free translation of parts of the official GitHub documentation Fork A Repo and Send pull requests .
So, what is the "request for inclusion (changes you have made)" (this is how I translated the pull request)? The official githab documentation says:
Speaking your language: By sending a pull request, you tell the author of the original repository (and all interested parties): “See what I did, would you like to accept my changes and inject them into the project?”
Two models of joint development are popular on GitHub:
Pull requests are particularly useful in the “Fork + Pull” model because they provide a way to notify the project maintainers (ie the owner of the original repository) about changes to your copy of the repository. However, they are also useful in the common repository model, where they are usually used to initiate a review or discussion of the code before including it in the main branch of development.
Considering the first development model, you need to have your own copy of the original repository, in which the work will be conducted, and changes from which will then be proposed to the author of the original repository.
')
As part of this tutorial, we will assume that we are working on the octocat user Spoon-Knife repository , and your username is username .
This is very easy to do: on the repository page there is a “Fork” button, which should be clicked.
After that, this copy can already be “pulled down” to your computer:
A cloned repository has one binding to a remote repository called origin, which points to your copy on GitHub, and not to the original repository, in order to track changes in it, you will need to add another binding, called, for example, upstream.
So, at this point we can already edit the code and make commits. If you have done all the previous steps in order to later return your changes to the original repository, then I strongly advise you to do all the work in a separate thematic development branch. The usefulness of this will become clear at the stage of sending a pull request. Let it be called feature.
Here, now do good (and let it be expressed in commits).
Once you’ve done the job (or part of it), send it to your copy of the repository on GitHub:
So, everything is done. You have written the code, it is in your branch “feature” both on your computer and on GitHub. It remains only to "send" it to the original repository.
Go to the page of your copy of the repository on GitHub, select the feature branch and click the Pull Request button.
Then you will be taken to a preview page, where you can enter the name and description of your changes (the name will then fall into the description of the Merge Commit and will be made public, keep this in mind).
There you can also see which commits hit the pull request:
As well as the general diff of all changes in the pull request:
By default, pull requests are considered to be based on the most frequently integrated branch of the parent repository. In this case, the username / Spoon-Knife was copied from octocat / Spoon-Knife, so the pull request is considered to be based on the octocat / Spoon-Knife master repository branch. In most cases, this will be correct, but if not, then you can click on the "Change Commits" button.
You will be taken to the form for selecting the base and source branches:
On the left, choose which branch the changes in the parent repository will join, on the right - what changes will be taken from your repository. Following the example: octocat / Spoon-Knife / master on the right, username / Spoon-Knife / feature on the left. Here you can specify not only branches, but also tags and id of individual commits in the corresponding repository.
IMPORTANT : Agree with the owner of the "parent" repository, in which branch you will add changes (he can write this in the README)
Changing the base repository also changes the list of people who receive notification of a pull request. Anyone who has the right to “write” to the base repository will receive a letter and see a notification on the main GitHub, the next time it enters.
Once the commit list satisfies you, click the Update Commit Range button.
When you have entered the name and description and rechecked the list of commits and changes to the files that fell into the pull request, click the Send pull request button. Pull rekvest will be created immediately.
Keep track of your pull request. What people will comment on, what the maintainer will say, whether or not your pull request will be accepted.
Remember, I said that you should keep all the changes that will go into the pool in a separate branch? So, the main convenience: you can always add commits to an already existing pull request, simply adding them to this thread in your repository (yes, yes, just a
When viewing the pull request, in addition to the name, description, and commits, the following are also displayed:
In the comments to the pull request, you can use Markdown, that is, you can insert images and use all the formatting supported by Markdown.
When your pull request is accepted, do not forget to merge the changes into your repository (or delete it if you no longer need it):
You can also delete the branch in which the development was carried out:
You can simply pour changes from the original repository to yourself:
However, the owner of the original repository, or maybe even you, will not like the presence of merge commits and commits from the master in the list of commits for pool. In this case, you should use git rebase.
Read about how rebase works in the official manual . There are very clear illustrations. There is also an article in the help of GitHub.
ATTENTION: Please note that git rebase changes the commit id! Therefore, all actions with this command should be performed only on the local repository, before these commits become publicly available , i.e. before you push them on the githab.
If the pull request satisfies all the conditions, then someone with “write” (i.e. can push) to the target repository should accept pull request by one of many methods. The following are the three most popular methods:
In many cases, you can ask github to automatically accept a pull request using the large green Merge Pull Request button, which will inject changes, create a merge commit and close the pull request.
More details can be found in this habratopic: The merge button on GitHub .
The main method of infusion of changes. It requires adding a remote leading to the repository of the person who sent the pull request, downloading changes from this repository, merging the desired branch, fixing conflicts, and unloading the updated branch back to the original repository:
The previous method works well when you work in a team or constantly accept changes from the same group of people. The other method is a bit faster in isolated cases when using git-am.
Each pull request has its own .patch URL from which you can download a text patch to feed it to the git-am command:
Pull requests are automatically closed when the requested commits join the destination repository. At the same time, an event is generated informing all the development participants that the pull request was accepted and merged into the main branch.
It is also possible to manually close the pull request if it was rejected. Sometimes this is necessary in cases where the changes were made using git-cherry-pick or another mechanism that does not allow to detect the fact of a merge.
I hope this guide will help you in improving many open-source (and not only) projects.
Despite the great time spent on Habrahabr, this is my first topic. Please report in a personal or in the comments about all the shortcomings that I could allow. I will correct.
Many thanks to Antiarchitect and other habrauser for their help in publishing the article, as well as, of course, the GitHub development team, for such a convenient and free service for open-source service.
So, what is the "request for inclusion (changes you have made)" (this is how I translated the pull request)? The official githab documentation says:
Pull requests let you tell others about the changes you posted in your GitHub repository. Once the pull request has been submitted, interested parties review your changes, discuss possible edits, or even add complementary commits, if needed.
Speaking your language: By sending a pull request, you tell the author of the original repository (and all interested parties): “See what I did, would you like to accept my changes and inject them into the project?”
A bit about collaborative development models
Two models of joint development are popular on GitHub:
- The “Fork + Pull” model allows anyone to fork an existing repository and merge changes into their personal fork without having to access the original repository. Then, changes should be included in the source repository by its owner. This model reduces the number of movements for new contributors and is popular for open source projects, as it allows people to work independently, without a single coordination.
- The “Shared Repository Model” model is more common for small teams and organizations working on closed projects. Everyone in the team has write access to one common repository, and topic branches are used to isolate changes.
Pull requests are particularly useful in the “Fork + Pull” model because they provide a way to notify the project maintainers (ie the owner of the original repository) about changes to your copy of the repository. However, they are also useful in the common repository model, where they are usually used to initiate a review or discussion of the code before including it in the main branch of development.
Making a copy of the repository
Considering the first development model, you need to have your own copy of the original repository, in which the work will be conducted, and changes from which will then be proposed to the author of the original repository.
')
As part of this tutorial, we will assume that we are working on the octocat user Spoon-Knife repository , and your username is username .
This is very easy to do: on the repository page there is a “Fork” button, which should be clicked.
After that, this copy can already be “pulled down” to your computer:
git clone git@github.com:username/Spoon-Knife.git A cloned repository has one binding to a remote repository called origin, which points to your copy on GitHub, and not to the original repository, in order to track changes in it, you will need to add another binding, called, for example, upstream.
cd Spoon-Knife git remote add upstream git://github.com/octocat/Spoon-Knife.git git fetch upstream Doing work
So, at this point we can already edit the code and make commits. If you have done all the previous steps in order to later return your changes to the original repository, then I strongly advise you to do all the work in a separate thematic development branch. The usefulness of this will become clear at the stage of sending a pull request. Let it be called feature.
git checkout -b feature # , "feature" Here, now do good (and let it be expressed in commits).
Once you’ve done the job (or part of it), send it to your copy of the repository on GitHub:
git push origin feature # origin feature Return changes: Pull request
So, everything is done. You have written the code, it is in your branch “feature” both on your computer and on GitHub. It remains only to "send" it to the original repository.
Go to the page of your copy of the repository on GitHub, select the feature branch and click the Pull Request button.
Then you will be taken to a preview page, where you can enter the name and description of your changes (the name will then fall into the description of the Merge Commit and will be made public, keep this in mind).
There you can also see which commits hit the pull request:
As well as the general diff of all changes in the pull request:
By default, pull requests are considered to be based on the most frequently integrated branch of the parent repository. In this case, the username / Spoon-Knife was copied from octocat / Spoon-Knife, so the pull request is considered to be based on the octocat / Spoon-Knife master repository branch. In most cases, this will be correct, but if not, then you can click on the "Change Commits" button.
You will be taken to the form for selecting the base and source branches:
On the left, choose which branch the changes in the parent repository will join, on the right - what changes will be taken from your repository. Following the example: octocat / Spoon-Knife / master on the right, username / Spoon-Knife / feature on the left. Here you can specify not only branches, but also tags and id of individual commits in the corresponding repository.
IMPORTANT : Agree with the owner of the "parent" repository, in which branch you will add changes (he can write this in the README)
Changing the base repository also changes the list of people who receive notification of a pull request. Anyone who has the right to “write” to the base repository will receive a letter and see a notification on the main GitHub, the next time it enters.
Once the commit list satisfies you, click the Update Commit Range button.
When you have entered the name and description and rechecked the list of commits and changes to the files that fell into the pull request, click the Send pull request button. Pull rekvest will be created immediately.
What's next?
Keep track of your pull request. What people will comment on, what the maintainer will say, whether or not your pull request will be accepted.
Remember, I said that you should keep all the changes that will go into the pool in a separate branch? So, the main convenience: you can always add commits to an already existing pull request, simply adding them to this thread in your repository (yes, yes, just a
git push origin feature , provided that you specified the source thread in the pull request) )When viewing the pull request, in addition to the name, description, and commits, the following are also displayed:
- Comments left to pull request;
- Additional commits added to the pull request branch;
- Comments on modified lines or files left to any of the commits included in the pull request.
In the comments to the pull request, you can use Markdown, that is, you can insert images and use all the formatting supported by Markdown.
When your pull request is accepted, do not forget to merge the changes into your repository (or delete it if you no longer need it):
git checkout master git pull upstream master git push origin master You can also delete the branch in which the development was carried out:
git branch -d feature # git push origin :feature # What should be done if the work took a lot of time and the original repository managed to go ahead?
You can simply pour changes from the original repository to yourself:
git checkout master git pull upstream master git checkout feature git merge master However, the owner of the original repository, or maybe even you, will not like the presence of merge commits and commits from the master in the list of commits for pool. In this case, you should use git rebase.
git checkout master git pull upstream master git checkout feature git rebase master # Read about how rebase works in the official manual . There are very clear illustrations. There is also an article in the help of GitHub.
ATTENTION: Please note that git rebase changes the commit id! Therefore, all actions with this command should be performed only on the local repository, before these commits become publicly available , i.e. before you push them on the githab.
If you are the master: How to accept pull request
If the pull request satisfies all the conditions, then someone with “write” (i.e. can push) to the target repository should accept pull request by one of many methods. The following are the three most popular methods:
Auto Merge
In many cases, you can ask github to automatically accept a pull request using the large green Merge Pull Request button, which will inject changes, create a merge commit and close the pull request.
More details can be found in this habratopic: The merge button on GitHub .
Fetch and Merge (download and merge)
The main method of infusion of changes. It requires adding a remote leading to the repository of the person who sent the pull request, downloading changes from this repository, merging the desired branch, fixing conflicts, and unloading the updated branch back to the original repository:
git checkout master git remote add username git://github.com/username/Spoon-Knife.git git fetch username git merge username/feature git push origin master Patch and Apply (patch and accept)
The previous method works well when you work in a team or constantly accept changes from the same group of people. The other method is a bit faster in isolated cases when using git-am.
Each pull request has its own .patch URL from which you can download a text patch to feed it to the git-am command:
git checkout master curl https://github.com/octocat/Spoon-Knife/pull/50.patch | git am git push origin master Closing pull request
Pull requests are automatically closed when the requested commits join the destination repository. At the same time, an event is generated informing all the development participants that the pull request was accepted and merged into the main branch.
It is also possible to manually close the pull request if it was rejected. Sometimes this is necessary in cases where the changes were made using git-cherry-pick or another mechanism that does not allow to detect the fact of a merge.
Instead of conclusion
I hope this guide will help you in improving many open-source (and not only) projects.
Despite the great time spent on Habrahabr, this is my first topic. Please report in a personal or in the comments about all the shortcomings that I could allow. I will correct.
Many thanks to Antiarchitect and other habrauser for their help in publishing the article, as well as, of course, the GitHub development team, for such a convenient and free service for open-source service.
Source: https://habr.com/ru/post/125999/
All Articles