Denis Costa said:
- Pull request
This course will become read-only in the near future. Tell us at community.p2pu.org if that is a problem.
In the last task we have learnt how we can contribute to a project. Now it is time to actually participate in the project and get our hands dirty :-)
If you have successfully completed the previous tasks, you will have in your Github account a project that you have forked. As we have explained, now you have a copy or clone of the original project, so you can work in your personal sandbox without breaking anything.
Once you have the copy in your Github account, you can download it into your computer and work on it. Basically you will follow the next steps to get the copy into your computer:
Please, read the full documentation about this process in the official Github Help Page.
With the project cloned into your desktop, now you are ready to add that awesome feature that is missing from the original project, or fixing an issue that you have discovered, or adding a new logo, translation, etc.
Github uses the git tool to track versions of the files of the project. As you have cloned the original project, you have your own copy with all the previous versions of the files. Git works basically as a time machine that allows you to see the evolution of changes for a file over time.
By default when you cloned the repository or project into your computer, git has created for you a master branch. This branch is a snapshot of the original project when you forked it. If you want you can work directly here, but you would prefer to avoid it. Why? Because master branches should be considered clean and stable, so we should create a new working branch to implement or fix an issue for the project.
Creating a new working branch AGAIN? Yes, we have to, but do not worry, git will help you with the process and actually you will see how easy it is. Git can manage as many branches as you want, so in the Github community it is very common to create a branch for every issue. When the issue has been solved, this branch will be merged with the master one, and published publicly in the web.
Therefore, you have a pristine copy of the original software and you have chosen an issue that you want to solve. In Github every issue has a unique ID: a number. As we are going to work in that issue, it is a good habit to name the branch like this: issue-numberId-small-description. Why? Because it will help you to know in what you are working on at every moment, and other developers will be able to know in what you are working.
The steps to create this new working branch are the following:
As we now have a new working branch, we can start adapting whatever we want. Git will know that you are modifying files from the original project, so it will allow you to see which files have been modified. If you are running git from the command line, you can run: git status to see in which branch you are currently working, which files you have modified and which files are new.
You will keep adding new files, and modifying existing ones until you fix the issue. Once you have fixed it, you are ready to commit the changes or modifcations to the repository so we can create a new version of the files. In order to commit the changes, we have to first tell git which files do we want to commit, so we will tell git which files we want to add to the commit:
If we run again git status, we will see that we have 3 files (as in this example) added to the commit. Now we can commit the changes locally in our own computer and in the current working branch with the command: git commit. After running the command, we will be prompted to write a small description of the changes. This is very important, as it will help other contributors to know what we have changed.
This message usually follows a style that mimics the e-mail format. The first line is used as the subject (you should describe in a few words what you have completed) and then, after a blank line you will have the body of the message or the large explanation of the changes. For example, something like this:
1: Fix for issue #13 new description added. Closes #13
3: This fix changes ...............
Thus, let's summarize what we have done so far:
Fine, we are almost there! We have fixed an issue and we have committed the changes, but locally. If you remember we are working in a cloned copy of the original project. Furthermore, we have created another branch to add our changes without breaking the master branch. Now we have the changes in our new branch, but we have not populated the changes to the master branch. How do we do it?
Well we only have to change the working branch to master and merge it:
This will apply the changes to the master branch, but again locally. If you check your Github account you will see that none of these improvements are available online. The reason is that Git is a distributed system, so it allows you to work locally and only push changes to the online repository when you are ready. If we want to push the changes to your Github forked repository, you have to run the following commands: git push This will upload the changes to your repository and they will be publicly available for everyone on the web.
If you check at this moment the history link of the forked project in your Github account you will see the short message that you wrote when you committed the changes. Now you want to notify to the upstream project that you have solved the issue, right? Well, all you have to do is to click in the pull request button and you will be prompted to write a small message about your changes, so the original developers can review it and merge the code if they like it (check the official help page from Github)
The goal of this challenge is to create a new branch for the issue that you have adopted it. Fixit, and commit the changes to your forked copy of the project. Then you should submit a pull request for the original project and post here the link to the pull request that you have created. It will be also very good if you describe all the steps that you have followed to finish this task.
- Pull request