Difference between revisions of "Using the Github UI to Make Pull Requests"

From Joomla! Documentation

(Marked this version for translation)
 
(33 intermediate revisions by 8 users not shown)
Line 3: Line 3:
 
Tutorial</translate>}}
 
Tutorial</translate>}}
 
<translate><!--T:2-->
 
<translate><!--T:2-->
This article helps you understanding and creating Pull Requests on Github, so you can contribute to a project like Joomla!.</translate>
+
This article helps you understanding and creating Pull Requests on Github, so you can contribute to a project like Joomla!. Many changes, including bug fixes and feature additions can be implemented and reviewed via the normal GitHub pull request workflow.
 +
 
 +
<!--T:33-->
 +
Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a consensus among the community and the core team.
 +
</translate>
 +
 
 +
<translate>
 +
== Before making a pull request == <!--T:28-->
 +
</translate>
 +
<translate>
 +
<!--T:29-->
 +
A hastily proposed pull request can hurt its chances of acceptance. Low quality proposals, proposals for previously rejected features, may be quickly rejected, which can be demotivating for the unprepared contributor. Laying some groundwork ahead of the pull request can make the process smoother.
 +
 
 +
<!--T:34-->
 +
Although there is no single way to prepare for submitting a pull request, it is generally a good idea to pursue feedback from other project developers beforehand to ascertain that the pull request may be desirable. Although it may seem like a useful feature or bug fix, there may be reasons it cannot work that you have not considered (or could not know about).
 +
 
 +
<!--T:35-->
 +
As a rule of thumb, receiving encouraging feedback from long-standing project developers, and particularly members of the core team or existing contributors, is a good indication that the pull request is worth pursuing.  To get feedback, we suggest you join the [https://volunteers.joomla.org/ Volunteers Portal] and join RingCentral (still referred to as Glip, just ask a team lead in the Volunteers portal to add you) to ask other developers.  Once you are ready, we suggest, before doing any code, you submit an issue to the [https://issues.joomla.org Joomla! issue tracker] with "RFC" at the beginning.  That will create a request for comments which will help you to identify any additional work or issues you may have to overcome to get your idea accepted.
 +
</translate>
  
 
<translate>
 
<translate>
Line 9: Line 27:
 
</translate>
 
</translate>
 
<translate><!--T:4-->
 
<translate><!--T:4-->
A Pull Request is a <b>request</b> to <b>pull</b> some code to a repository (project) on GitHub.</translate>
+
A Pull Request is a '''request''' to '''pull''' some code to a repository (project) on GitHub.</translate>
  
 
<translate><!--T:5-->
 
<translate><!--T:5-->
In basic language your asking if some code changes/additions you made can be used in the project. This changes can be the solution for a bug or a new feature.</translate>
+
You are asking if some code changes or a new piece of code you have written can be added to the project codebase. The changes can be a solution to solving a bug or a new feature.</translate>
 
<translate><!--T:6-->
 
<translate><!--T:6-->
Github has a simple web interface that makes it very easy to propose a simple change to code. You don't need to install any software or do anything beside register for a git hub account.</translate>
+
GitHub has a simple web interface that makes it very easy to propose a simple change to code. You don't need to install any software or do anything beside register for a GitHub account.</translate>
  
 
<translate>
 
<translate>
== Identify the change you like to made == <!--T:7-->
+
== Identify the change you would like to made == <!--T:7-->
 
</translate>
 
</translate>
 
<translate><!--T:8-->
 
<translate><!--T:8-->
First of all, map what changes you like to made.</translate>
+
Be clear of the problem you wish to solve and do check through pull requests already made to see if someone has already started a solution. You may be able to help or enhance it.</translate>
  
 
<translate><!--T:9-->
 
<translate><!--T:9-->
For example, we like to add an icon for at the article info block, before the authors name. On the moment of writing, this icon is not displayed yet.</translate>
+
In this example, the contributor has seen that the alias is on the same line as the title and wraps. The solution, add a line break so that it is forced onto a new line</translate>
 
 
[[File:Infoblock before.png|frame|none]]
 
  
 +
[[File:Before-patch.jpg|The situation before the patch is applied]]
 
<translate>
 
<translate>
 
== Find the file you want to modify on Github== <!--T:10-->
 
== Find the file you want to modify on Github== <!--T:10-->
 
</translate>
 
</translate>
 
<translate><!--T:11-->
 
<translate><!--T:11-->
If you don't have a GitHub account yet, sign up on [http://www.github.com GitHub]. It is free and very easy to do. After that, go to the [http://www.github.com/joomla/joomla-cms Joomla! CMS repository] and find the file you like to edit. You can navigate through by clicking on the folder and file name.</translate>
+
If you don't have a GitHub account yet, sign up on [https://github.com GitHub]. It is free. Go to the [https://github.com/joomla/joomla-cms Joomla! CMS repository] and find the file you like to edit. You can navigate through the files and folders by clicking on the folder to drill down the file tree until you find the file you want then click on the file name.</translate>
  
 +
<translate>
 +
<!--T:32-->
 +
Before you start navigating through the files check that you are in the right <code>branch</code> There is a dropdown box to the left next to the 'New pull request' button. It will show staging which is the current branch of the CMS being worked on <code>Staging</code>. For the development of the next 3.10 version. <code>3.10-dev</code> and <code>4.0-dev</code>. Branch names can change! Ask fellow Joomla developers if you are not sure which branch to select.</translate>
 +
[[File:Files-on-github.jpg|An example of the files in the Joomla GitHub repository]]
 
<translate><!--T:12-->
 
<translate><!--T:12-->
This can be a hard step sometimes, because Joomla! counts more than 6000 files. In our example we have to edit the following file: /layouts/joomla/content/info_block/author.php.</translate>
+
Find the files you need to change. In our example, we have to edit the following files:  
 +
* administrator/components/com_categories/tmpl/categories/default.php
 +
* administrator/components/com_categories/tmpl/categories/modal.php
 +
* administrator/components/com_content/tmpl/articles/default.php
 +
* administrator/components/com_content/tmpl/featured/default.php
 +
</translate>
  
[[File:Github joomlacms.png|thumbnail|none]]
+
[[File:The files changed2.png|The files changed]]
  
 
<translate>
 
<translate>
Line 42: Line 68:
 
</translate>
 
</translate>
 
<translate><!--T:14-->
 
<translate><!--T:14-->
Navigate to the file, and edit the file by clicking on the pencil icon on the right.</translate>
+
Navigate to the files, and edit the files by clicking on the pencil icon on the right.</translate>
  
 
<translate><!--T:15-->
 
<translate><!--T:15-->
In our example, we add the following code to line 14 of the file: <tt>autor.php</tt></translate>
+
In our example, four files were edited so that the alias could be styled to go onto the next line. Origionally with a line brake but in discussion it was changed to a div</translate>
 +
<source lang="xml">
 +
<div class=
 +
</source>
 +
and a closing
 
<source lang="xml">
 
<source lang="xml">
<span class="icon-user"></span>
+
</div>
 
</source>
 
</source>
  
[[File:Github_filechange.png|thumbnail|none]]
+
[[File:Edit-github2.jpg|The files to be edited on GitHub]]
  
 
<translate><!--T:16-->
 
<translate><!--T:16-->
Note: you may have noticed the blue message above the page. This message is telling you that GitHub made a copy of the project for you, where you can made changes. This copy is called a Fork. The changes you made in this copy can be used in the original project.  If you like to read more about how GitHub works, [https://guides.github.com/introduction/flow/ you can read this article] for some background information.</translate>
+
Note: you may have noticed the blue message above the page. This message is telling you that GitHub made a copy of the project for you, where you can make changes. This copy is called a Fork. The changes you made in this copy can be used in the original project.  If you would like to read more about how GitHub works, [https://guides.github.com/introduction/flow/ you can read this article] for some background information.</translate>
  
 
<translate>
 
<translate>
Line 59: Line 89:
 
</translate>
 
</translate>
 
<translate><!--T:18-->
 
<translate><!--T:18-->
Below the editor, we can specify our Pull Request by adding a title and a description.</translate>  
+
Below in the editor, we can give our Pull Request a title and a description.</translate>  
  
 
<translate><!--T:19-->
 
<translate><!--T:19-->
The title had to be sort, and must tell what this pull request does.
+
The title has to be short and must explain what this pull request does.
  
 
<!--T:26-->
 
<!--T:26-->
Line 68: Line 98:
 
</translate>
 
</translate>
  
[[File:Github description.png|thumbnail|none]]
 
  
 +
[[File:Describe-changes.jpg|Describe the changes]]
 
<translate>
 
<translate>
  
Line 75: Line 105:
 
</translate>
 
</translate>
 
<translate><!--T:21-->
 
<translate><!--T:21-->
Click on the button "Propose file changes" and after that on the button "Create Pull Request". You pull request is made now!
+
Click on the button "Propose file changes" and after that on the button "Create Pull Request". Your pull request is made now!
 +
</translate>
 +
 
 
[[File:Create pull request.PNG|framed|center]]
 
[[File:Create pull request.PNG|framed|center]]
</translate>
 
  
 
<translate>
 
<translate>
Line 83: Line 114:
 
</translate>
 
</translate>
 
<translate><!--T:23-->
 
<translate><!--T:23-->
The only thing you had to do now is waiting until someone see this PR and test it. When someone reacts, you will be notified via an email. It may happen someone requested addition information, so try to stay up-to-date with you Pull Request.</translate>
+
The only thing you have to do now is wait until someone will test this PR. When someone comments, you will be notified via an email. It can happen that someone requests addition information, so try to stay up-to-date with you Pull Request.</translate>
  
 
<translate><!--T:24-->
 
<translate><!--T:24-->
If a Pull Request is twitce successfully tested, someone with moderator right will add the label 'RTC' to it. RTC means: Ready To Commit'. In basic language it tells someone who has admin right: He, this Pull request is successfully tested, and can be add to Joomla!. The admin will add (Merge) the project to the Joomla! CMS github repository. You Pull Request is definitive now, and well be present in the next version of Joomla!.</translate>
+
If a Pull Request is successfully tested twice, a moderator will add the label 'RTC' to it. RTC means: Ready To Commit'. In basic language it tells someone who has commit rights: This Pull request is successfully tested, and can be added to Joomla!. The admin will add (Merge) the project to the Joomla! CMS github repository. Your Pull Request is definitive now, and will be present in the next version of Joomla! if it was about fixing a bug or in the next minor version if the PR was about a new feature.</translate>
  
 
<noinclude>
 
<noinclude>

Latest revision as of 11:12, 21 September 2021

Other languages:
Deutsch • ‎English • ‎Nederlands • ‎español • ‎français
Tutorial

This article helps you understanding and creating Pull Requests on Github, so you can contribute to a project like Joomla!. Many changes, including bug fixes and feature additions can be implemented and reviewed via the normal GitHub pull request workflow.

Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a consensus among the community and the core team.

Before making a pull request[edit]

A hastily proposed pull request can hurt its chances of acceptance. Low quality proposals, proposals for previously rejected features, may be quickly rejected, which can be demotivating for the unprepared contributor. Laying some groundwork ahead of the pull request can make the process smoother.

Although there is no single way to prepare for submitting a pull request, it is generally a good idea to pursue feedback from other project developers beforehand to ascertain that the pull request may be desirable. Although it may seem like a useful feature or bug fix, there may be reasons it cannot work that you have not considered (or could not know about).

As a rule of thumb, receiving encouraging feedback from long-standing project developers, and particularly members of the core team or existing contributors, is a good indication that the pull request is worth pursuing. To get feedback, we suggest you join the Volunteers Portal and join RingCentral (still referred to as Glip, just ask a team lead in the Volunteers portal to add you) to ask other developers. Once you are ready, we suggest, before doing any code, you submit an issue to the Joomla! issue tracker with "RFC" at the beginning. That will create a request for comments which will help you to identify any additional work or issues you may have to overcome to get your idea accepted.

What is a Pull Request?[edit]

A Pull Request is a request to pull some code to a repository (project) on GitHub.

You are asking if some code changes or a new piece of code you have written can be added to the project codebase. The changes can be a solution to solving a bug or a new feature. GitHub has a simple web interface that makes it very easy to propose a simple change to code. You don't need to install any software or do anything beside register for a GitHub account.

Identify the change you would like to made[edit]

Be clear of the problem you wish to solve and do check through pull requests already made to see if someone has already started a solution. You may be able to help or enhance it.

In this example, the contributor has seen that the alias is on the same line as the title and wraps. The solution, add a line break so that it is forced onto a new line

The situation before the patch is applied

Find the file you want to modify on Github[edit]

If you don't have a GitHub account yet, sign up on GitHub. It is free. Go to the Joomla! CMS repository and find the file you like to edit. You can navigate through the files and folders by clicking on the folder to drill down the file tree until you find the file you want then click on the file name.

Before you start navigating through the files check that you are in the right branch There is a dropdown box to the left next to the 'New pull request' button. It will show staging which is the current branch of the CMS being worked on Staging. For the development of the next 3.10 version. 3.10-dev and 4.0-dev. Branch names can change! Ask fellow Joomla developers if you are not sure which branch to select. An example of the files in the Joomla GitHub repository Find the files you need to change. In our example, we have to edit the following files:

  • administrator/components/com_categories/tmpl/categories/default.php
  • administrator/components/com_categories/tmpl/categories/modal.php
  • administrator/components/com_content/tmpl/articles/default.php
  • administrator/components/com_content/tmpl/featured/default.php

The files changed

Make your changes[edit]

Navigate to the files, and edit the files by clicking on the pencil icon on the right.

In our example, four files were edited so that the alias could be styled to go onto the next line. Origionally with a line brake but in discussion it was changed to a div

<div class=

and a closing

</div>

The files to be edited on GitHub

Note: you may have noticed the blue message above the page. This message is telling you that GitHub made a copy of the project for you, where you can make changes. This copy is called a Fork. The changes you made in this copy can be used in the original project. If you would like to read more about how GitHub works, you can read this article for some background information.

Add a title and description[edit]

Below in the editor, we can give our Pull Request a title and a description.

The title has to be short and must explain what this pull request does.

The description contains more detailed information about the Pull request and some information how to test it. Make this information so complete and clear as possible. When you made a Pull Request of an issue on GitHub, it is very common to add also the issue ID in the description. You can do this by typing a # (hash tag) with directly following the issue ID. You can find this ID directly after the title of the issue, in the same notation.


Describe the changes

Send the Pull Request[edit]

Click on the button "Propose file changes" and after that on the button "Create Pull Request". Your pull request is made now!

Create pull request.PNG

And now?[edit]

The only thing you have to do now is wait until someone will test this PR. When someone comments, you will be notified via an email. It can happen that someone requests addition information, so try to stay up-to-date with you Pull Request.

If a Pull Request is successfully tested twice, a moderator will add the label 'RTC' to it. RTC means: Ready To Commit'. In basic language it tells someone who has commit rights: This Pull request is successfully tested, and can be added to Joomla!. The admin will add (Merge) the project to the Joomla! CMS github repository. Your Pull Request is definitive now, and will be present in the next version of Joomla! if it was about fixing a bug or in the next minor version if the PR was about a new feature.