Ready to contribute code? Here’s what you need to know to get your Pull Request accepted.
The PrestaShop project receives dozens of contributions every week, and every single one of them is reviewed by project maintainers. The review process ensures that only changes that meet a certain quality standard are merged in the codebase.
Please note that the following guidelines apply to all contributions to the project. Not following them may lead to your contribution to be rejected.
Each time you want to work on a contribution, create a dedicated branch, based on the appropriate branch from the project (described below). Using separate branches for your contributions will allow you to update your contributions easily during the code review process, and submit multiple contributions at the same time.
Contributions may be made to the appropriate branch, depending on the nature of your change.
PrestaShop only accepts contributions on branches which are subject to new releases.
Once a minor “dot-zero” version has been released, no new patch releases will be made for previous versions. This means that only the latest minor version patch branch is supported – with the exception of rare cases, like a security bug being found just before or after a minor release is published.
For example, the
1.7.4.x branch is supported until version 126.96.36.199 is released. After that, the only supported version branch will be
1.7.5.x, and so on.
If you find a bug on an unsupported version, make sure that bug is still present in the latest version. If the bug is still present, please submit a Pull Request on
Pull Requests for unsupported versions will be closed.
Make atomic commits, meaning that each commit’s purpose should be one, and only one, complete fix or change. Typically, ask yourself if what you are doing is one or several tasks.
Atomic commits make review easier, and it also helps for cherry-picking or reverting changes (we hope to never have to do that 😉).
The commit name should give an idea of the nature and context of the change that has been done. The more details, the better! The commit name should be as unique and recognizable as your commit itself. There are multitude of articles on the web regarding commit messages, here are two that you can find useful: How to Write a Git Commit Message and What makes a good commit message?.
Bad commit messages give pretty much no context:
add cli new
fix useless code
fix code review comments
A good commit message explains what is done, and why. Here’s an example:
Make Source.indexOf(ByteString) significantly faster Previously the algorithm that did this was extremely inefficient, and had worst case runtime of O(N * S * S) for N is size of the bytestring and S is the number of segments. The new code runs in O(N * S). It accomplishes this by not starting each search at the first segment, which could occur many times when called by RealBufferedSource.
Make sure to follow these guidelines:
Changes submitted through your Pull Request will be reviewed by PrestaShop maintainers. The code review process is generally regarded as a good practice and adopted by hundreds of software projects around the world. It provides lot of benefits:
And don’t forget that reviewing is a discussion, not a to-do list: the goal is to find the best solution by sharing different points of view.
However, reviewing code is hard and can be exhausting. Making your pull request as easy to review as possible will help in getting it accepted swiftly. Completing the pull request form (explained below) properly, explaining the reasons behind some of your technical choices as well as any part of the code that could be tricky to understand… those are some examples of things that you can do to help ease up the process.
Avoid submitting very large PRs when it can be avoided.
Remember: smaller changes are easier to review, easier to test and easier to merge.
When you create a new Pull Request, you will be presented with a form that looks like this:
(click on it to see full size)
The first step is to write a summary of your pull request’s purpose in its GitHub title.
A Pull Request title should be short, but precise enough to describe the changes it introduces and how they impact the software.
Please respect the following rules:
Here are some good examples:
Why this is important?
Pull Requests titles are used to build the Changelog we publish on each release. Here’s an example.
Once you have chosen a title for your Pull Request, you are asked to fill out the Pull Request table. Filling it out properly is mandatory.
Along other reasons, it helps maintainers:
Let’s see what each of the rows is for.
This part is needed to cross-check that your PR targets the branch that you intended. Just write the name of the target branch, as explained above in Choosing the right base branch.
Describing your change and the reasoning behind it is extremely important for it to be reviewed and approved. Explain, in as much detail as you can, what did you change and why.
If you need space, just write a short summary about your change in the table, then describe in more detail below it. You are also encouraged to add links, files, screenshots… anything that can help reviewers understand why the change is needed, and why it’s valid.
Use this Pull Request as an example if you find yourself short on inspiration.
Type is used to describe what kind of a change your Pull Request is. Refer to the following table to choose the most appropriate:
|bug fix||The changes fix a bug.|
|improvement||The changes improve an already existing feature (eg. cosmetic or UX changes, performance improvement, etc).|
|new feature||The changes introduce a functionality that didn’t exist before (eg. add a button, a new page, a new block…)|
|refacto||The changes only refactor code, without changing any of its side effects.|
The category is the portion of the project to which your changes apply to. We use this code alongside with the type to construct the changelog by grouping changes in different sections. Choose the code that most closely describes your change:
|FO||The changes impact the Front Office|
|BO||The changes impact the Back Office|
|IN||The changes impact the Installer|
|WS||The changes impact the Web Services|
|CO||The changes impact the Core (non-visible functionality)|
|LO||The changes impact localization functionality|
|TE||The changes impact automated tests|
|ME||The changes only import a git branch into another (eg. merge maintenance branch into develop)|
|PM||The changes are related to project management (eg. edit Github pull request form)|
It is very important to note if your change introduces backwards incompatible changes (“backward compatiblity breaks”).
Here are some examples of changes that can be considered breaking changes:
If your code introduces deprecations, please note them here.
If your Pull Request resolves an existing issue, please note it using the magic word “Fixes”, followed by the issue number, like this:
If no issue is linked to your Pull Request, maintainers might ask you to create one. This helps the team track what goes in a release and the status of each individual change.
In addition to being code reviewed, each individual contribution is manually verified by PrestaShop’s QA team. In order to effectively confirm that your change doesn’t introduce new errors, please describe how to best verify that your change does what you expect it to do. Feel free to write as much details as you can outside the table if needed.
Adding third party software in the core or in a module might sometimes be faster and easier than to develop it from scratch and then to maintain it. Composer and NPM are used to manage such dependencies in the PrestaShop open source project.
It is possible to add new dependencies, after a careful selection and study. A few rules must be followed.
The first step is to check the legal compliance of a third party software. The PrestaShop open source project being written and distributed under the OSL license, aggregated dependencies must be compatible with it.
Below is a list of the known compatible licenses that can accepted for software:
Additionally, artwork (e.g: icons, pictures, fonts, but not only) is usually distributed with specific licenses. Below is a list of known compatible licenses that can be accepted for artwork:
In general, public domain is not acceptable, as it doesn’t exist in all juridictions or countries.
If the proposed dependency is available with a compliant license, a last check is done to be sure that there is no additional clause that would introduce a restriction of use.
If the legal compliance is confirmed, it will be possible to go the next step: the technical review.