Page History

...

If all this sounds like a foreign language, you should learn about Git and Github first. Go to the "Understand Git" section of this page.

...

Complete process to your first pull request

In this process, we will work on Windows and use the TortoiseGit tool. Be sure to install it before you start. You can download it here: http://code.google.com/p/tortoisegit/wiki/Download?tm=2.
There are many more available GUI tools for Git on both Windows and OS X: http://git-scm.com/downloads/guis.
If you are using a Unix system, we figure you should be happier with Git's own command line tool . Read all about it here: http://git-scm.com/book.

...

1. Go to the PrestaShop Github repository.
2. Fork the project by clicking on the "Fork" button. The fork will appear as a "PrestaShop" repository in your own account.
   You've successfully forked the PrestaShop repository, but so far it only exists on your Github account. To be able to work on the project, you will need to clone it to your local machine.
3. On your local machine:
   1. Clone your fork:
      1. Create a new folder on your local machine. We'll name it "PS-MyChanges", but you can use whatever name you want.
      2. Get the HTTPS clone URL from your Github PrestaShop repository. It should resemble this: https://github.com/xBorderie/PrestaShop.git
      3. Right-click on you PS-MyChanges folder, and in the Git section of the menu that appears, choose "Git Clone..."
      4. In the window that opens, paste the clone URL in the "URL" field.
      5. Click OK: TortoiseGit will download the files and folders from your Gihub repo.
   2. (optional) Add the "upstream" remote: When a repository is cloned, it has a default remote repository called "origin" that points to your fork on GitHub, not the original PrestaShop repository it was forked from. To keep track of the changes in the original repository and keep your local clone updated, you need to add another remote named "upstream":
      
      1. Right-click on the PrestaShop folder in the PS-MyChanges folder (it should have a green mark if no change has been made yet), and in the ToroiseGit submenu, choose "Settings..."
      2. Open the Git/Remote section of the option panel.
      3. Type "upstream" in the "Remote field".
      4. From PrestaShop Github repository, copy the HTTPS clone URL and paste it in TortoiseGit's "URL" field.
      5. Click the "Add new/Save" button. TortoiseGit asks you if you want to disable tag fetching: choose "No".
      6. TortoiseGit asks you if you want to fetch remote branches from the newly added remote: choose "Yes".
      7. TortoiseGit displays a summary window: click "OK". A window will open showing that Git is fetch fetching data. Close it once it is done, and close the still-open Settings window.
   3. Make your changes:
      1. Edit all the necessary files. As soon as you save and edited file, Windows will change its icon from green to red to indicate that it has been changed since the last update.
   4. Submit your changes to your Github repository:
      
      1. Once you are done editing the local files, reach the root of your local repository (the "PrestaShop" folder in PS-MyChanges).
      2. Right-click on the folder and choose "Git Gui". This will open an interface. The files you have changed should appear in the "Staged Changes (Will commit)" section. If they are in the "Unstage Changes" window instead, select them and click on the "Stage Changed" button to move them to the "Staged Changes" section.
      3. Write a commit message for your changes. Be sure to follow the commit message norm.
      4. Click the "Commit" button: your changes are now committed to your local Git repository.
      5. Click the "Push" button: a window opens, asking you to which branch the commit should be pushed – usually it should be "1.6". Leave "origin" as the remote setting, and click "Push".
      6. TortoiseGit open a window showing the current status, and might also open an OpenSSH window asking you for your Github username, then your Github password. Give them both and validate: the status window should push your changes to your Github repository. Success! You can close the TortoiseGit windows: the rest will happen on Github.
4. Submit your changes to the PrestaShop repository: Now that your changes are stored on Github, you need to let them be known to the PrestaShop developers. This is done by creating a "pull request", which can be seen as a suggestion all the files you have committed. Github has an excellent help page about creating pull requests, but here is a summary:
   
   1. Go to your own PrestaShop repository on Github.
   2. Either click on the "Pull Request" or the "Compare" button. Both will open the same screen, comparing your latest commit to the original code.
   3. The top of the screen indicates what is being compared. It should be PrestaShop's 1.6 branch with your own 1.6 branch. You should not have anything to change here, just make sure that the base fork is the PrestaShop repository, and that your own repository is the head fork.
   4. Click on the "Create a pull request" button. A new screen should appear, in which you can review your changes and edit your commit message (it should already use the commit message you used from your local clone).
   5. Click on the "Send pull request" button: Github open a screen where you can start a conversation about your pull request, right in PrestaShop's Github repository. Congratulation, your changes are now ready to add to the PrestaShop codebase!
5. Wait for one of the core developers either to include your change in the codebase, or to comment on possible improvements you should make to your code.

Understanding Git

...

Keeping your fork and clone up to date

If you plan on contributing to PrestaShop for anything more than a very quick fix, you should make your fork track the official PrestaShop repository. This is what you should have done in the optional 3.b. step, "Add the 'upstream' remote" – and you can still do it now!

Here is how to set up the local upstream remote:

1. Right-click on the PrestaShop folder in the PS-MyChanges folder, and in the ToroiseGit submenu, choose "Settings..."
2. Open the Git/Remote section of the option panel.
3. Type "upstream" in the "Remote field".
4. From PrestaShop Github repository, copy the HTTPS clone URL and paste it in TortoiseGit's "URL" field.
5. Click the "Add new/Save" button. TortoiseGit asks you if you want to disable tag fetching: choose "No".
6. TortoiseGit asks you if you want to fetch remote branches from the newly added remote: choose "Yes".
7. TortoiseGit displays a summary window: click "OK". A window will open showing that Git is fetching data. Close it once it is done, and close the still-open Settings window.

Now you can update the local clone:

1. Right-click on the PrestaShop folder in the PS-MyChanges folder, and choose "Git sync..."
2. In the window that appears, choose "upstream" as the remote URL, and click on "Pull".
3. TortoiseGit displays status information, downloads the latest data from your upstream remote URL (which should be https://github.com/PrestaShop/PrestaShop.git), and finally displays the latest changes from upstream, which have now been merged to your local repository.

Your local clone is now up to date, but you might want your fork on Github to also be on par with the upstream repository. You cannot do this from one Github repo to another, but TortoiseGit can do the trick for you, right after you have updated your local clone:

1. Open the Git Sync window if it is not yet open: right-click on the PrestaShop folder in the PS-MyChanges folder, and choose "Git sync..."
2. Choose "origin" as the remote URL, and click on "Push".
3. ortoiseGit displays status information, uploads the latest data from your origin remote URL, and finally displays the "Success" message.

You're done!

Making further pull requests

You can continue editing your local copy of PrestaShop and submit your changes to the PrestaShop developers with the process we explained earlier. Here it is again, in a simpler form:

1. On your local machine:
   1. Make your changes:
      1. Edit all the necessary files. As soon as you save and edited file, Windows will change its icon from green to red to indicate that it has been changed since the last update.
   2. Submit your changes to your Github repository:
      
      1. Once you are done editing the local files, reach the root of your local repository (the "PrestaShop" folder in PS-MyChanges).
      2. Right-click on the folder and choose "Git Gui". This will open an interface. The files you have changed should appear in the "Staged Changes (Will commit)" section. If they are in the "Unstage Changes" window instead, select them and click on the "Stage Changed" button to move them to the "Staged Changes" section.
      3. Write a commit message for your changes. Be sure to follow the commit message norm.
      4. Click the "Commit" button: your changes are now committed to your local Git repository.
      5. Click the "Push" button: a window opens, asking you to which branch the commit should be pushed – usually it should be "1.6". Leave "origin" as the remote setting, and click "Push".
      6. TortoiseGit open a window showing the current status, and might also open an OpenSSH window asking you for your Github username, then your Github password. Give them both and validate: the status window should push your changes to your Github repository. Success! You can close the TortoiseGit windows: the rest will happen on Github.
2. Submit your changes to the PrestaShop repository: Now that your changes are stored on Github, you need to let them be known to the PrestaShop developers. This is done by creating a "pull request", which can be seen as a suggestion all the files you have committed. Github has an excellent help page about creating pull requests, but here is a summary:
   
   1. Go to your own PrestaShop repository on Github.
   2. Either click on the "Pull Request" or the "Compare" button. Both will open the same screen, comparing your latest commit to the original code.
   3. The top of the screen indicates what is being compared. It should be PrestaShop's 1.6 branch with your own 1.6 branch. You should not have anything to change here, just make sure that the base fork is the PrestaShop repository, and that your own repository is the head fork.
   4. Click on the "Create a pull request" button. A new screen should appear, in which you can review your changes and edit your commit message (it should already use the commit message you used from your local clone).
   5. Click on the "Send pull request" button: Github open a screen where you can start a conversation about your pull request, right in PrestaShop's Github repository. Congratulation, your changes are now ready to add to the PrestaShop codebase!
3. Wait for one of the core developers either to include your change in the codebase, or to comment on possible improvements you should make to your code.

Welcome to the fabulous world of Git collaboration!

Understanding Git

The Github website has more information on how to fork a repo, how to use pull requests and many more articles on Github collaboration, but the best way to go is to learn more about Git and Github:

• The Git book: http://git-scm.com/book
• git ready: http://gitready.com/
• Git Immersion: http://gitimmersion.com/
• Think Like (a) Git: http://think-like-a-git.net/
• Git cheatsheet: http://byte.kde.org/~zrusin/git/git-cheat-sheet-medium.png
• Try Github: http://try.github.io/
• Github help: https://help.github.com/
• Rich Jones: How to GitHub: Fork, Branch, Track, Squash and Pull Request

Making changes directly in Github

...