Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Most of the instructions on this page will require you to create your own GitHub account.

If you already know how to work with Git/GitHub

Then you're all set! Please work exclusively with pull requests.

Here are technical information:

  • Contributing to PrestaShop Core:
    • Use this repository: https://github.com/PrestaShop/PrestaShop
    • Branches to use for your pull requests:
      • 'develop' for the forthcoming PrestaShop 1.7: new features, major changes, etc.
      • '1.6.1.x' for the current PrestaShop 1.6: bugfixes and security fixes only, NO NEW FEATURE, even small ones.
        The PR's merger will take care of porting your fix to the 'develop' branch
  • Contributing to a native module:
    • Each native module has its own repository. For instance, https://github.com/PrestaShop/autoupgrade
    • Branches to use:
      • 'dev' for everything: fixes, new features, etc.
      • 'master' is only used by the Core devs for the released version.

A few things to keep in mind:

Read the Build devblog regularly in order to get the latest news!

Working using Git

This is the recommended way of contributing code to PrestaShop Core.

In order to make changes to PrestaShop's core code, you first need to create a local fork of PrestaShop, or at least have your own GitHub repository. When your changes are done, you must send your work to the PrestaShop developers for approval. This means installing a tool to retrieve the PrestaShop code from GitHub, editing it on your machine, and sending your changes back to PrestaShop's GitHub repository.

...

In the process presented herein, we will work on Windows and use the TortoiseGit tool. Be sure to install it before you start. You can download it here: httphttps://codetortoisegit.google.com/p/tortoisegit/wiki/Download?tm=2org/.
There are many more available GUI tools for Git on both Windows and OS X: http://git-scm.com/downloads/guis. Windows users should also install the Git for Windows extension:http https://msysgit.GitHubgit-for-windows.github.io/ (with the "Git bash here" option enabled).
If you are using a Unix system, we figure you should be happier with Git's own command line tool (smile). Read all about it here: http://git-scm.com/book.

Info
titleCloning with the modules

Since March 20th, 2014, all of PrestaShop's default modules have been moved into their own GitHub repositories (or "submodules"). This implies a few changes on your side:

  • You are starting afresh:
    • You are cloning the project: add the --recursive option in order to also clone all the module's repositories (or check the "Recursive" box in TortoiseGit). See below for more about the process.
  • You already have a local clone:
    • You want to update your cloned project: use git pull && git submodule update --init --recursive
    • You want to switch the submodules on the master branch: use git submodule foreach git checkout master
    • You want to retrieve the submodules log files: use git submodule foreach git log

...

  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, with all the original branches.
    Image RemovedImage Added
    You've successfully forked the PrestaShop repository, but so far it only exists on your GitHub account. To be able to properly 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, preferably in your local webserver's public file folder ('www', 'htdocs', or something else depending on our installation).
        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/your-username/PrestaShop.git
      3. Right-click on your PS-MyChanges folder, and in the Git section of the menu that appears, choose "Git Clone..."
      4. In the "Git clone" window that opens, paste the clone URL in the "URL" field and remove the final "\PrestaShop" mention in the "Directory" field, so that the files are downloaded at the root of the folder.
        Finally, do not forget to check the "Recursive" box so that you will also get all the default modules!

        Note

        If you forgot to tick the "Recursive" checkbox when cloning your fork, use a command line terminal (shell, Bash, etc.) and enter these commands:

        git submodule init
        git submodule update

         

      5. Click OK: TortoiseGit will download the files and folders from your GitHub repo.
    2. (optional) Add the "upstream" remote: When a repository is cloned, it has a default remote repository called "origin" that should point to your fork on GitHub, not to the original PrestaShop repository from which it was forked. To keep track of the changes in the original repository and keep your local clone updated, you need to add another remote URL 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 at the bottom of the TortoiseGit submenu, choose "Settings". This opens the Settings panel.
      2. Open the Git > Remote section of the Settings panel.
      3. Remote field: Type "upstream".
      4. URL field: put the HTTPS clone URL from the official PrestaShop GitHub repository: https://github.com/PrestaShop/PrestaShop.git .
      5. Click the "Add new/Save" button. TortoiseGit asks you if you want to disable tag fetching for this remote: choose "No", since this remote IS an official remote.
      6. TortoiseGit asks you if you want to fetch remote branches from the newly added remote: choose "Yes".
      7. TortoiseGit displays the Fetch window for PS-MyChanges: 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 (which should by now list "upstream" below "origin" in the list of remote URLs).

...

  1. Reach the root of your local repository (the folder above PS-MyChanges). Right-click on the PS-MyChanges and choose "Git Commit -> 1develop.6...", with "1.6develop" being your current local branch. This will open the Commit window. The files you have changed should appear in the "Changes made" section.

    • Make sure to only commit the files that you meant to change for this feature/bugfix, but not any other changed files! For instance, PrestaShop and its modules might change some configuration files: do not ever commit them!
      If there are files that you did not change yourself or do not want to commit at this time, simply deselect them before clicking "OK".
  2. Write a commit message for your changes. Be sure to follow the commit message norm!
  3. Click the "OK" button: your changes are now committed to your local Git repository. Click "Close".
  4. Right-click on the PS-MyChanges folder and choose "Git Sync...": the Git Synchronization window opens, asking you which local branch should be pushed to which remote branch – usually it should be "1.6develop" in both cases, unless you have created a specific local branch your set of changes. Leave "origin" as the remote URL since you can only push your changes to your own repository on GitHub (and not the "upstream" official repository for PrestaShop), and click "Push".
  5. TortoiseGit updates the window with 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.
  6. Success! You can close the TortoiseGit windows: the rest of the process will happen on GitHub.

...

  1. Go to your own PrestaShop repository on GitHub.
  2. Either click on the "Pull Request" button 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 "develop" branch with your own 1.6 "develop" branch. You should not have anything to change here: just make sure that the base fork is the PrestaShop repository at branch 1.6"develop", and that the head fork is your own repository at the branch you pushed your changes to.
    If GitHub says "There isn't anything to compare", you might have forgotten a step in this tutorial.
  4. Click on the "Create a pull request" button. A new screen should appear, in which you can review your changes and give your pull request a title (it should already use the commit message you used from your local clone).

    • This title is only for internal use at GitHub: it helps the PrestaShop developers, but only your local commit message is kept in the project's Git history. In any case, most of the time you won't need to edit the title: keep the commit message.
  5. Click on the "Send pull request" button: GitHub opens a screen where you can start a conversation about your pull request, right in PrestaShop's GitHub repository.
  6. Congratulation, your changes are now ready to add to the PrestaShop codebase!

...

  1. On your local machine:
    1. Always pull the latest changes from the upstream repository. This will prevent bad surprises, where you cannot push your changes until you have merged the ones that were made by other developers!
    2. 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.
    3. Submit your changes to your GitHub repository:
      1. Once you are done editing the local files, reach the root of your local repository (the folder above PS-MyChanges).
      2. Right-click on the PS-MyChanges and choose "Git Commit -> 1.6develop", with "1.6develop" being your current branch. This will open an interface window. The files you have changed should appear in the "Changes made" section.
      3. Write a commit message for your changes. Be sure to follow the commit message norm.
      4. Click the "OK" button: your changes are now committed to your local Git repository. Click "Close".
      5. Right-click on the PS-MyChanges and choose "Git Sync...": a window opens, asking you to which branch the local commit should be pushed – usually it should be "1.6develop". Leave "origin" as the remote URL, and click "Push".
      6. TortoiseGit updates the window with 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 (see above).
      7. Success! You can close the TortoiseGit windows: the rest will happen on GitHub.
  2. Submit your changes to the PrestaShop repository:
    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 "develop" branch with your own 1.6 "develop" 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.

...

They are separated on the main repository, but since you made a recursive clone of PrestaShop, they were all downloaded by Git as if they were part of PrestaShop. You MUST do another step in order to have a proper setup:

  1. Right-click on the your clone folder (in this example, PS-MyChanges) and choose the "Git bash here" option. If you do not have it, install Git for Windows (http://msysgit.github.io/) with "Git bash here" option enabled.
  2. In the bash window that opens, type this command: "git submodule update --init" (without the quotes).

...

GitHub will then automatically create a new fork with a "1.6develop" branch on your own GitHub account, then suggest to create a pull request to PrestaShop: just write a commit message (follow the PrestaShop commit message norm!), and validate. Once the pull request is submitted, you just have to wait for a core developer to act on it.

...

Note

Make sure that you are always making changes to the latest version of the original repository. This means that the "Branch" button above the list of file should read "branch: 1.6develop", and not "branch: master":

  • The 1.6 "develop" branch is the one where all current works for PrestaShop 1.7 are pushed to.
    • The "1.6.1.x" is used solely for fix on the "1.6" version of PrestaShop
  • The "master" branch is a snapshot of the development branch which was used to build the previous release of PrestaShop.
  • The "release" branch (if available) is the forthcoming release.
  • Others branches are for specific current projects, and should not be touched.