When you create a new Pull Request, you will be presented with a form that looks like this:
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 in Supported branches.
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.
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 behavior 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 main part of the project affected by your changes. 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)|
Why is this important?
We use type & category to group changes in the changelog.
It is very important to note if your change introduces backwards incompatible changes (also referred to as “backward compatibility breaks” or “BC 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:
Fixes #12314. If your Pull Request fixes multiple issues, use following syntax:
Resolves #12314, Resolves #56789.
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.
This field should contain links to related PRs in other repositories.
If your Pull Request modifies database structure or adds new configuration fields, you should also provide a PR for autoupgrade module.
If your Pull Request needs a theme change to work, you should provide hummingbird and classic-theme PR.
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.
Think about tests!
Including automated tests (unit, integration or functional) that verify your changes can significantly increase the chances that your Pull Request is accepted.
PrestaShop’s QA team will not only verify the right behavior of your change but also verify that other related parts of the software are still working as expected. For example modifying a CSS class can disrupt the display of all the web pages which rely on it. Please mention all the impacts you are aware of that need to be checked in order to help QA team find and verify all of them.