The Pull Request form

When you create a new Pull Request, you will be presented with a form that looks like this:

Screenshot of the New Pull Request Form

The first step is to write a summary of your pull request’s purpose in its GitHub title.

Writing a good 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:

  • Be descriptive. Avoid laconic or non-descriptive sentences, like “Fix bug” or “Update file.php”.
  • Write full sentences. Avoid writing sentences without verbs, like “Yaml standards”.
  • Use the imperative mood (eg. “Add foo bar” instead of “Added…” or “Adding”). This will help keep changelog style coherent.
  • Don’t include references. Don’t add issue references like "#12314 Fix issue on…" or tags like "[BO] Fix bug where…". The PR table is there for that.

Here are some good examples:

  • Fix fatal error when trying to sign up on Chrome
  • Prevent users from deleting their own profile on the users listing
  • Reduce memory usage on the Front Office home
  • Add button to close the welcome message on first login
  • Migrate product page to Symfony

Why this is important?

Pull Requests titles are used to build the Changelog we publish on each release. Here’s an example.

The Pull Request form

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:

  • Make sure that the change works as expected
  • Track when a change fixes a known issue
  • Track if a change introduced affects backwards compatibility (BC breaks)
  • Build the change log (changes are grouped by type and category).

Let’s see what each of the rows is for.

Branch

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.

Description

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.

Tip: If you find yourself short on inspiration, use this Pull Request as an example.

Type & Category

Type is used to describe what kind of a change your Pull Request is. Refer to the following table to choose the most appropriate:

Type Scope
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:

Code Scope
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)
Remember, this is only needed for the Pull Request form, not for your commit messages.

Why is this important?

We use type & category to group changes in the changelog.

BC breaks

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:

  • Change any public method signature in any class (rename, change its return type or structure, remove a parameter, or change its type).
  • Change any public property in any class.
  • Rename, move, or delete any class or class namespace.
  • Add new requirements (like dropping support for old versions of PHP or browsers, requiring new server-side libraries, etc.)
  • Replace any subsystem (like updating libraries to new major versions or replacing a library with another).
Be aware that introducing a breaking change, even when justified, may force maintainers to reject your Pull Request.

Deprecations

If your code introduces deprecations, please note them here.

Fixed ticket

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.

Using the appropriate syntax will link your Pull Request to that issue, and will automatically close it once your Pull Request is merged.

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.

How to test

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.

Possible impacts

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.