Creating a Pull Request¶
When creating a pull request:
- Clone the Sulu repository from git.
- Add a branch and name it after the following format:
<type>/<description>
, where type is one offeature
,bugfix
,hotfix
orenhancement
. For example:feature/what-my-pr-does
. Note that dashes should be used instead of spaces (not underscores). - Add your feature/bugfix/enhancement.
- Create atomic and logically separate commits (use the power of
git rebase
to have a clean and logical history). - Write good commit messages (see the tip below).
- Write tests.
- Test your Code.
- In case you do changes that break backwards compatibility you also have to
add a description to the
UPGRADE.md
file in the root directory. - Use a meaningful name for the pull request (see the tip below).
- Create the pull request as soon as possible.
- In addition to a pull request to the code repository, you should also send a pull request to the documentation repository to update the documentation when appropriate.
Tip
A good commit message is composed of a summary (the first line),
optionally followed by a blank line and a more detailed description. Use a
verb (Fixed ...
, Added ...
, …) to start the summary and don’t
add a period at the end.
If you are a member of the Sulu organization you should also:
- Add a label for the type of the PR:
- feature: provides a new feature
- enhancement: the PR improves existing features
- bugfix: provides a bug fix
- hotfix: the PR is a bugfix that should be made against a stable branch (e.g.
master
)
Template¶
When creating a pull request on GitHub, there is already a pre filled template for you. The template is divided in several parts.
Checklist¶
The pull request must include the following checklist at the top to ensure that contributions may be reviewed without needless feedback loops and that your contributions can be included into Sulu as quickly as possible:
An example submission could now look as follows:
| Q | A
| ------------------ | ---
| Bug fix? | yes
| New feature? | no
| BC breaks? | no
| Deprecations? | yes
| Fixed tickets | fixes #1243, fixes #1443
| Related issues/PRs | -
| License | MIT
| Documentation PR | sulu/sulu-docs#153
Some answers to the questions trigger some more requirements:
- If you answer yes to “Bug fix?”, check if the bug is already listed in the
Sulu issues and reference it/them in “Fixed tickets”. These should be of the
form
fixes #123, fixes #321
. - If you answer yes to “New feature?”, you must submit a pull request to the documentation and reference it under the “Documentation PR” section.
- If you answer yes to “BC breaks?”, the pull request must contain updates to
the
UPGRADE.md
file. - If you answer yes to “Deprecations?”, the pull request must contain updates to
the
UPGRADE.md
file. - If the “license” is not MIT, just don’t submit the pull request as it won’t be accepted anyway.
Note
When an issue number is prefixed with fixes
it tells GitHub to
automatically close the referenced ticket when the pull request is merged
What’s in this PR?¶
Give as much details as possible about your changes (don’t hesitate to give code examples to illustrate your points). The pull request description helps the code review and it serves as a reference when the code is merged.
Why?¶
If your pull request is about adding a new feature or modifying an existing one, explain the rationale for the changes. Why did you add this feature, which problem does the PR fix?
Example usage¶
If you add a new feature or make breaking changes, please give us an example usage (code examples, screenshots, etc.), so we understand what you try to solve.
Remove this section if not needed.
BC Breaks/Deprecations¶
If you have done BC breaks or deprecations, please describe them shortly here
and add them to the UPGRADE.md
file as well.
Remove this section if not needed.
To Do¶
If some of the requirements in the checklist are not met, use the “To Do” section and add the relevant items:
- [ ] Submit changes to the documentation
- [ ] Document the BC breaks
If the code is not finished yet because you don’t have time to finish it or because you want early feedback on your work, add an item to to-do list:
- [ ] Finish the code
- [ ] Add tests as they have not been updated yet
- [ ] Gather feedback for my changes
Remove this section if not needed.