Difference between revisions of "My first pull request to Joomla! on Github"

From Joomla! Documentation

m (Remove righttoc)
(Several markup and capitalization changes. URL corrections.)
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
== A Pull Request ?? ==
+
== A Pull Request? ==
So what the heck could be a "Pull Request" ? No, I bet it's not what you're thinking right now...
+
What is a ''Pull Request'' anyway?
  
A Pull Request is the Git Jargon meaning "I will send a '''request''' to a project, to '''pull''' in some code changes / additions I have made to their code base"
+
A Pull Request is the Git Jargon meaning "I will send a ''request'' to a project, to ''pull'' in some code changes/additions I have made to their code base"
  
Got it ? This is how we (including you) are going to contribute source code to the Joomla! code base.
+
Got it? This is how we (including you) are going to contribute source code to the Joomla! code base.
  
It might look a bit scary at first (at least to me) but in the end it's pretty easy - "similar" to SVN, but a lot better.
+
It might look a bit scary at first but in the end it's pretty easy - "similar" to SVN, but a lot better.
  
 
Here is how it works:
 
Here is how it works:
Line 13: Line 13:
 
The installation depends on the operating system you are using. If you use Linux, you may find the git software in your repository.
 
The installation depends on the operating system you are using. If you use Linux, you may find the git software in your repository.
  
For '''example''' [http://opensuse.org OpenSuSE] offers a "pattern" named <code>git</code> that provides the git core (required) as well as a set of tools like [http://gitk.sourceforge.net/ gitk], an e-mail interface, scripts to import source code from other version control systems like svn and others.
+
For example, [https://www.opensuse.org/ openSUSE] offers a ''pattern'' named ''git'' that provides the git core (required) as well as a set of tools like [http://gitk.sourceforge.net/ gitk], an e-mail interface, scripts to import source code from other version control systems like svn and others.
  
 
[[File:git-opensuse-install.png]]
 
[[File:git-opensuse-install.png]]
  
For more information about installing git on other operating systems see the GitHub site for [https://help.github.com/articles/set-up-git#platform-linux Linux], [https://help.github.com/articles/set-up-git#platform-mac Mac] and even [https://help.github.com/articles/set-up-git#platform-windows Windows].
+
For more information about installing git on other operating systems, see the GitHub site for [https://docs.github.com/en/get-started/quickstart/set-up-git#platform-linux Linux], [https://docs.github.com/en/get-started/quickstart/set-up-git#platform-mac Mac] and [https://docs.github.com/en/get-started/quickstart/set-up-git#platform-windows Windows].
  
For this tutorial you will also need [http://eclipse.org/pdt/ Eclipse PDT] with the [http://eclipse.org/egit/ eGit plugin] installed.
+
For this tutorial you will also need [https://www.eclipse.org/pdt/ Eclipse PDT] with the [https://www.eclipse.org/egit/ EGit plugin] installed.
 +
 
 +
== GitHub Work Flow for Joomla! ==
 +
 
 +
[[File:Github work flow joomla.png]]
  
 
== GitHub ==
 
== GitHub ==
For this tutorial we have created a GitHub user named '''<code>jlover</code>''' - a dude who loves J :)
+
For this tutorial we have created a GitHub user named ''jlover'' - a dude who loves Joomla.
  
He has already [http://help.github.com/fork-a-repo/ forked] the main repository so his repository is at: https://github.com/jlover/joomla-platform
+
He has already [https://docs.github.com/en/get-started/quickstart/fork-a-repo forked] the main repository so his repository is at: ''https://github.com/jlover/joomla-platform''
  
 
[[File:github-repo.png]]
 
[[File:github-repo.png]]
  
== Import your clone ==
+
== Import Your Clone ==
Mr. JLover uses Linux and his Eclipse workspace is at <code>/home/jlover/workspace</code>
+
Mr. JLover uses Linux and his Eclipse workspace is at ''/home/jlover/workspace''
  
Before eGit 1.0 it was not possible to create or clone repositories right into your workspace. To make things easier we set the default repository folder to our workspace.
+
Before EGit 1.0 it was not possible to create or clone repositories right into your workspace. To make things easier we set the default repository folder to our workspace.
  
 
[[File:git-eclipse-preferences-1.png]]
 
[[File:git-eclipse-preferences-1.png]]
  
Let's start. Go to your workspace, right click inside the PHP explorer and select '''Import...'''.
+
Let's start. Go to your workspace, right click inside the PHP explorer and select ''Import...''.
  
 
[[File:git-eclipse-import.png]]
 
[[File:git-eclipse-import.png]]
  
Select '''Git''' &rArr; '''Projects from Git'''
+
Select ''Git'' &rArr; ''Projects from Git''
  
 
[[File:git-eclipse-import-2.png]]
 
[[File:git-eclipse-import-2.png]]
  
Click on '''Clone...'''
+
Click on ''Clone...''
  
 
[[File:git-eclipse-import-3.png]]
 
[[File:git-eclipse-import-3.png]]
  
=== Source repository ===
+
=== Source Repository ===
  
In the window that opens up, copy and paste the HTTP URL from your GitHub repository. The remaining fields will be auto filled.
+
In the window that opens, copy and paste the HTTP URL from your GitHub repository. The remaining fields will be auto-filled.
  
 
Your may also want to supply your password but this is not required if you limit the write operations to the command line.
 
Your may also want to supply your password but this is not required if you limit the write operations to the command line.
Line 55: Line 59:
 
[[File:git-eclipse-import-4.png]]
 
[[File:git-eclipse-import-4.png]]
  
Select the branches you want to clone. The '''master''' branch is the ''point of truth''.
+
Select the branches you want to clone. The ''master'' branch is the ''point of truth''.
  
 
[[File:git-eclipse-import-5.png]]
 
[[File:git-eclipse-import-5.png]]
  
=== Local destination ===
+
=== Local Destination ===
Now choose where you want to save the files. We will save them in our workspace and modify the default name joomla-platform to '''my-joomla-platform'''.
+
Now choose where you want to save the files. We will save them in our workspace and modify the default name ''joomla-platform'' to ''my-joomla-platform''.
  
Please remember this name, as we will use it later when we create our project in the same folder.
+
Remember this name; we will use it later when we create our project in the same folder.
  
 
[[File:git-eclipse-import-6.png]]
 
[[File:git-eclipse-import-6.png]]
  
=== Receiving objects... ===
+
=== Receiving Objects ===
The files are being checked out. Sit back and watch patiently, or go for a cup of coffee ;)
+
The files are being checked out. Sit back and watch patiently, or go for a cup of coffee.
  
 
[[File:git-eclipse-import-6-checkout.png]]
 
[[File:git-eclipse-import-6-checkout.png]]
  
Finished. Click '''Next >'''
+
Finished. Click ''Next >''
  
 
[[File:git-eclipse-import-7.png]]
 
[[File:git-eclipse-import-7.png]]
  
== New Project wizard ==
+
== New Project Wizard ==
  
Select '''Use the New Project wizard''' and click '''Finish''' to start it (windows like..)
+
Select ''Use the New Project wizard'' and click ''Finish'' to start it. (Windows like...)
  
 
[[File:git-eclipse-create-project-1.png]]
 
[[File:git-eclipse-create-project-1.png]]
  
Select '''PHP''' &rArr; '''PHP Project'''
+
Select ''PHP'' &rArr; ''PHP Project''
  
 
[[File:git-eclipse-create-project-2.png]]
 
[[File:git-eclipse-create-project-2.png]]
  
For the Project name enter the name of the repository you previously cloned. '''my-joola-platform''' in our example.
+
For the Project name enter the name of the repository you previously cloned, ''my-joomla-platform'' in our example.
 +
 
 +
Observe the message beside the yellow triangle that appears when you finished inserting the Project name, telling you that the specified location already exists.
  
Observe the message beside the yellow triangle that appears when you finished inserting the Project name, telling you that the specified location already exists.<br />
+
This is okay and expected.
This is OK and expected.
 
  
 
[[File:git-eclipse-import-8.png]]
 
[[File:git-eclipse-import-8.png]]
  
Click '''Next >''' and include other libraries if required.
+
Click ''Next >'' and include other libraries if required.
  
 
[[File:git-eclipse-import-9.png]]
 
[[File:git-eclipse-import-9.png]]
Line 98: Line 103:
 
== Finished ==
 
== Finished ==
  
After you click Finish, the new project will be created in your workspace.
+
After you click ''Finish'', the new project will be created in your workspace.
  
'''Welcome to the Joomla! platform.'''
+
''Welcome to the Joomla! platform.''
  
 
[[File:git-eclipse-import-10.png]]
 
[[File:git-eclipse-import-10.png]]
  
== The upstream repository ==
+
== The Upstream Repository ==
  
OK. So far you have a local "clone" of your GitHub repository which is a fork of the main Joomla! repository.
+
Okay. So far you have a local "clone" of your GitHub repository which is a fork of the main Joomla! repository.
  
But what if the information in the main Joomla! repository changes ? Remember your fork (and your clone) are completely independent from the main repository. Fortunately git allows you to add multiple repositories to your "working copy" to track changes and merge them with your work.
+
What if the information in the main Joomla! repository changes? Remember your fork (and your clone) are completely independent from the main repository. Fortunately Git allows you to add multiple repositories to your "working copy" to track changes and merge them with your work.
  
We are going to add the main repository and call it '''upstream'''. To do this I use the console because I have not figured out yet how to do this in eclipse (@todo?)
+
We are going to add the main repository and call it ''upstream''. To do this I use the console because I have not figured out yet how to do this in Eclipse (@todo?)
  
 
<pre>
 
<pre>
Line 117: Line 122:
 
</pre>
 
</pre>
  
To „update“ your clone with the latest changes from the main repository use
+
To update your clone with the latest changes from the main repository use:
  
 
<pre>
 
<pre>
Line 124: Line 129:
 
</pre>
 
</pre>
  
This will '''fetch''' the changes from the upstream repository and '''merge''' the upstream/master branch into your current branch.
+
This will ''fetch'' the changes from the upstream repository and ''merge'' the upstream/master branch into your current branch.
  
== Code away... ==
+
== Code Away... ==
So what are you waiting for ? Go and fix this bug or implement this cool feature and give it back to the Joomla! project. It's as easy as clicking a button ;)
+
So what are you waiting for? Go and fix this bug or implement this cool feature and give it back to the Joomla! project. It's as easy as clicking a button.
  
 
An example:
 
An example:
  
Let's create a simple patch file using Eclipse. We're going to add a comment line to a file that is really important to Joomla! and then create a pull request in GitHub to the Joomla! project.
+
Let's create a simple patch file using Eclipse. We're going to add a comment line to a file that is important to Joomla! and then create a pull request in GitHub to the Joomla! project.
  
So if the developers decide that your changes are worth being included into the code base, all they have to do is pushing a button and your name gets graved in stone (aka changelog) and the respective ''blame'' will show your name as the author for the lines of code you changed - Is this cute or what ?
+
If the developers decide that your changes should be included into the code base, all they have to do is push a button and your name gets engraved in stone (AKA the changelog) and the respective ''blame'' will show your name as the author for the lines of code you changed.
  
== Create a feature branch ==
+
== Create a Feature Branch ==
Git provides a handy feature called [http://book.git-scm.com/3_basic_branching_and_merging.html Branches]. The concept is somewhat similar to SVN but the handling is completely different. This feature is also known as ''cheap branching''.
+
Git provides a handy feature called [https://book.git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell Branches]. The concept is similar to SVN but the handling is completely different. This feature is also known as ''cheap branching''.
  
So if you plan to make more submissions or just to keep your master branch clean, you should create a new branch.
+
If you plan to make more submissions or just keep your master branch clean, create a new branch.
  
Unfortunately Eclipses branching concept seems to differ a bit from the original. So I use the command line also for branching operations. @todo?
+
Unfortunately Eclipse's branching concept seems to differ a bit from the original. So I use the command line also for branching operations. @todo?
  
The shortcut for creating and switching to a new branch is <code>checkout -b</code> so we will create a new branch called '''<code>first-test</code>'''
+
The shortcut for creating and switching to a new branch is ''checkout -b'' so we will create a new branch called ''first-test''
  
 
<pre>
 
<pre>
Line 149: Line 154:
 
</pre>
 
</pre>
  
Note that the tree has also changed in eclipse (maybe you need to refresh)
+
Note that the tree has also changed in Eclipse. (Maybe you need to refresh.)
  
 
[[File:git-eclipse-tree-details.png]]
 
[[File:git-eclipse-tree-details.png]]
  
OK we can now change whatever we want without "polluting" our master branch. The disk space required to do this is minimal. That's what is meant by ''cheap''...
+
We can now change whatever we want without "polluting" our master branch. The disk space required to do this is minimal. That's what is meant by ''cheap''...
 
 
== Change the code ==
 
Let's open the file <code>libraries/joomla/application/application.php</code>. and make a test change.
 
  
You really should feel a bit important right now doing changes to such an important Joomla! core file - do you ? ;).
+
== Change the Code ==
 +
Let's open the file ''libraries/joomla/application/application.php'' and make a test change.
  
Note that after you save the file, a ''dirty'' marker <code>></code> appears. You can change this in the configuration if you prefer the svn icon overlays.
+
Note that after you save the file, a ''dirty'' marker ''>'' appears. You can change this in the configuration if you prefer the SVN icon overlays.
  
 
[[File:git-pull-test-change.png]]
 
[[File:git-pull-test-change.png]]
  
That looks good. Now here comes another new concept if you are new to git: To get your changes to you repository on GitHub '''<big>two steps</big>''' are required:
+
That looks good. Here's another new concept if you are new to Git: To get your changes to you repository on GitHub '''two''' steps are required:
  
 
== Step 1 - Commit ==
 
== Step 1 - Commit ==
This step will commit your changes to your '''local''' repository. You can do this from within eclipse selecting the file(s) or folders you want to include in the commit.
+
This step will commit your changes to your ''local'' repository. You can do this from within Eclipse by selecting the files or folders you want to include in the commit.
  
 
Right click you project and select Team &rArr; Commit...
 
Right click you project and select Team &rArr; Commit...
Line 173: Line 176:
 
[[File:git-eclipse-commit-1.png]]
 
[[File:git-eclipse-commit-1.png]]
  
In the window that opens enter a meaningfull commit message
+
In the window that opens enter a meaningful commit message
  
 
[[File:git-eclipse-commit-2.png]]
 
[[File:git-eclipse-commit-2.png]]
  
After you press <code>Commit</code> note that the ''dirty'' marker <code>></code> has disappeared.
+
After you press ''Commit'' note that the ''dirty'' marker ''>'' has disappeared.
  
 
You may add as many commits as you like locally before submitting it to the server.
 
You may add as many commits as you like locally before submitting it to the server.
Line 189: Line 192:
  
 
<pre>git push origin first-test</pre>
 
<pre>git push origin first-test</pre>
This will push your changes to '''<code>origin</code>''' (your (jlovers) repository on GitHub) and create a new branch named '''<code>first-test</code>'''
+
This will push your changes to ''origin'' (your ''jlovers'' repository on GitHub) and create a new branch named ''first-test''
  
Done. Your changes are on the internet. Let's check out the GitHub site
+
Done. Your changes are on the internet. Let's check out the GitHub site:
  
 
[[File:git-pull-feed-1.png]]
 
[[File:git-pull-feed-1.png]]
Line 197: Line 200:
 
Looks good.
 
Looks good.
  
A nice feature in eclipse is the history view
+
A nice feature in Eclipse is the history view.
  
 
[[File:git-eclipse-history-view.png]]
 
[[File:git-eclipse-history-view.png]]
  
 
== The Pull Request ==
 
== The Pull Request ==
At this point we are finally ready to do our pull request. Let's go to our repository, be sure that you are on the correct branch (you may change this later), and find the '''Pull Request''' button.
+
At this point we are finally ready to do our pull request. Let's go to our repository. Be sure that you are on the correct branch. (You may change this later.) Find the ''Pull Request'' button.
  
Push it softly, nothing will really happen yet ;)
+
Push it softly, nothing will really happen yet.
  
 
[[File:github-pull-request-1.png]]
 
[[File:github-pull-request-1.png]]
  
On the next screen you should enter a meaningful message to the developers.
+
On the next screen enter a meaningful message to the developers.
  
Pay attention to the text white on black that shows '''from''' and '''to''' which repository:branch you are going to send your pull request. By pushing the button '''Change Commits''' you may modify those values.
+
Pay attention to the text white on black that shows ''from'' and ''to''. That's the ''repository:branch'' to which you are going to send your pull request. By pushing the button ''Change Commits'' you may modify those values.
  
 
[[File:github-pull-request-2.png]]
 
[[File:github-pull-request-2.png]]
Line 219: Line 222:
  
 
== Push the Button ==
 
== Push the Button ==
Ok, we are ready to '''Push the Button''' [[File:Button_send_pull_request.png]]
+
Okay, we are ready to ''Push the Button'' [[File:Button_send_pull_request.png]]
 
 
Thank you for your attention and in advance for your contribution(s) to the Joomla! project.
 
 
 
  
 
[[Category:Bug Squad]]
 
[[Category:Bug Squad]]
 
[[Category:Development]]
 
[[Category:Development]]
 
[[Category:GitHub]]
 
[[Category:GitHub]]

Latest revision as of 17:10, 28 October 2022

A Pull Request?[edit]

What is a Pull Request anyway?

A Pull Request is the Git Jargon meaning "I will send a request to a project, to pull in some code changes/additions I have made to their code base"

Got it? This is how we (including you) are going to contribute source code to the Joomla! code base.

It might look a bit scary at first but in the end it's pretty easy - "similar" to SVN, but a lot better.

Here is how it works:

Installation[edit]

The installation depends on the operating system you are using. If you use Linux, you may find the git software in your repository.

For example, openSUSE offers a pattern named git that provides the git core (required) as well as a set of tools like gitk, an e-mail interface, scripts to import source code from other version control systems like svn and others.

Git-opensuse-install.png

For more information about installing git on other operating systems, see the GitHub site for Linux, Mac and Windows.

For this tutorial you will also need Eclipse PDT with the EGit plugin installed.

GitHub Work Flow for Joomla![edit]

Github work flow joomla.png

GitHub[edit]

For this tutorial we have created a GitHub user named jlover - a dude who loves Joomla.

He has already forked the main repository so his repository is at: https://github.com/jlover/joomla-platform

Github-repo.png

Import Your Clone[edit]

Mr. JLover uses Linux and his Eclipse workspace is at /home/jlover/workspace

Before EGit 1.0 it was not possible to create or clone repositories right into your workspace. To make things easier we set the default repository folder to our workspace.

Git-eclipse-preferences-1.png

Let's start. Go to your workspace, right click inside the PHP explorer and select Import....

Git-eclipse-import.png

Select GitProjects from Git

Git-eclipse-import-2.png

Click on Clone...

Git-eclipse-import-3.png

Source Repository[edit]

In the window that opens, copy and paste the HTTP URL from your GitHub repository. The remaining fields will be auto-filled.

Your may also want to supply your password but this is not required if you limit the write operations to the command line.

Git-eclipse-import-4.png

Select the branches you want to clone. The master branch is the point of truth.

Git-eclipse-import-5.png

Local Destination[edit]

Now choose where you want to save the files. We will save them in our workspace and modify the default name joomla-platform to my-joomla-platform.

Remember this name; we will use it later when we create our project in the same folder.

Git-eclipse-import-6.png

Receiving Objects[edit]

The files are being checked out. Sit back and watch patiently, or go for a cup of coffee.

Git-eclipse-import-6-checkout.png

Finished. Click Next >

Git-eclipse-import-7.png

New Project Wizard[edit]

Select Use the New Project wizard and click Finish to start it. (Windows like...)

Git-eclipse-create-project-1.png

Select PHPPHP Project

Git-eclipse-create-project-2.png

For the Project name enter the name of the repository you previously cloned, my-joomla-platform in our example.

Observe the message beside the yellow triangle that appears when you finished inserting the Project name, telling you that the specified location already exists.

This is okay and expected.

Git-eclipse-import-8.png

Click Next > and include other libraries if required.

Git-eclipse-import-9.png

Finished[edit]

After you click Finish, the new project will be created in your workspace.

Welcome to the Joomla! platform.

Git-eclipse-import-10.png

The Upstream Repository[edit]

Okay. So far you have a local "clone" of your GitHub repository which is a fork of the main Joomla! repository.

What if the information in the main Joomla! repository changes? Remember your fork (and your clone) are completely independent from the main repository. Fortunately Git allows you to add multiple repositories to your "working copy" to track changes and merge them with your work.

We are going to add the main repository and call it upstream. To do this I use the console because I have not figured out yet how to do this in Eclipse (@todo?)

cd /home/jlover/workspace/my-joomla-platform
git remote add upstream git://github.com/joomla/joomla-platform.git

To update your clone with the latest changes from the main repository use:

git fetch upstream
git merge upstream/master

This will fetch the changes from the upstream repository and merge the upstream/master branch into your current branch.

Code Away...[edit]

So what are you waiting for? Go and fix this bug or implement this cool feature and give it back to the Joomla! project. It's as easy as clicking a button.

An example:

Let's create a simple patch file using Eclipse. We're going to add a comment line to a file that is important to Joomla! and then create a pull request in GitHub to the Joomla! project.

If the developers decide that your changes should be included into the code base, all they have to do is push a button and your name gets engraved in stone (AKA the changelog) and the respective blame will show your name as the author for the lines of code you changed.

Create a Feature Branch[edit]

Git provides a handy feature called Branches. The concept is similar to SVN but the handling is completely different. This feature is also known as cheap branching.

If you plan to make more submissions or just keep your master branch clean, create a new branch.

Unfortunately Eclipse's branching concept seems to differ a bit from the original. So I use the command line also for branching operations. @todo?

The shortcut for creating and switching to a new branch is checkout -b so we will create a new branch called first-test

cd /home/jlover/workspace/my-joomla-platform
git checkout -b first-test

Note that the tree has also changed in Eclipse. (Maybe you need to refresh.)

Git-eclipse-tree-details.png

We can now change whatever we want without "polluting" our master branch. The disk space required to do this is minimal. That's what is meant by cheap...

Change the Code[edit]

Let's open the file libraries/joomla/application/application.php and make a test change.

Note that after you save the file, a dirty marker > appears. You can change this in the configuration if you prefer the SVN icon overlays.

Git-pull-test-change.png

That looks good. Here's another new concept if you are new to Git: To get your changes to you repository on GitHub two steps are required:

Step 1 - Commit[edit]

This step will commit your changes to your local repository. You can do this from within Eclipse by selecting the files or folders you want to include in the commit.

Right click you project and select Team ⇒ Commit...

Git-eclipse-commit-1.png

In the window that opens enter a meaningful commit message

Git-eclipse-commit-2.png

After you press Commit note that the dirty marker > has disappeared.

You may add as many commits as you like locally before submitting it to the server.

Commit often.

Step 2 - Push[edit]

This step will submit your code to the GitHub server(s).

We do this from the command line @todo?

git push origin first-test

This will push your changes to origin (your jlovers repository on GitHub) and create a new branch named first-test

Done. Your changes are on the internet. Let's check out the GitHub site:

Git-pull-feed-1.png

Looks good.

A nice feature in Eclipse is the history view.

Git-eclipse-history-view.png

The Pull Request[edit]

At this point we are finally ready to do our pull request. Let's go to our repository. Be sure that you are on the correct branch. (You may change this later.) Find the Pull Request button.

Push it softly, nothing will really happen yet.

Github-pull-request-1.png

On the next screen enter a meaningful message to the developers.

Pay attention to the text white on black that shows from and to. That's the repository:branch to which you are going to send your pull request. By pushing the button Change Commits you may modify those values.

Github-pull-request-2.png

Here you can preview the changes you are proposing.

Github-pull-request-3.png

Push the Button[edit]

Okay, we are ready to Push the Button Button send pull request.png