Create a Patch¶
So you want to fix a bug or add a new feature to TYPO3? Great!
Step by Step Walkthrough¶
If you already walked through the manual up to here and performed all steps for setting up your accounts and setting up a working TYPO3 installation for core development, skip to number 6: “Make your changes to the code”!
More information: Setting up Your Accounts
Setup your TYPO3 installation
More information: Setup the TYPO3 installation.
Setup your TYPO3 installation usig the git cloned TYPO3 source:
mkdir t3master;cd t3master git clone email@example.com:typo3/typo3 .
Use DDEV if you want a quick and simple setup without having to install all system requirements.
Setup your git environment
More information: Git Setup
Setup name and email (same as you used for typo3.org), replace
git config user.name "Your Name" git config user.email "firstname.lastname@example.org"
git config branch.autosetuprebase remote
Setup commit-msg hook:
cp Build/git-hooks/commit-msg .git/hooks/commit-msg
Push to Gerrit (replace
git config remote.origin.pushurl ssh://<YOUR_TYPO3_USERNAME>@review.typo3.org:29418/Packages/TYPO3.CMS.git git config remote.origin.push +refs/heads/master:refs/for/master
Setup your IDE to adhere to the coding guidelines
More information: Setup your IDE
.editorconfigin the TYPO3 core directory to setup your IDE. As
.editorconfigonly contains minimal rules, it is a good idea to additionally setup your IDE to use PSR-1 / PSR-2 for PHP files.
Create an Issue on Forge
More information: Report an Issue
Every patch must have a matching issue on Forge, so create an issue now or submit a patch for an existing issue.
Make your changes to the code, add documentation, tests
This part is pretty straightforward. But be warned, there are still a few dark places deep inside the TYPO3 core dating back to the medieval times of PHP4. Yes, TYPO3 has been around for quite some time now. And there is ancient code we didn’t have to touch yet because it just works.
Make sure to look at How to deprecate classes, methods, arguments and hooks in the TYPO3 core in the Appendix for information about to deprecate things if you need to make changes to the public API.
For new features, breaking changes and deprecations, it is necessary to add information to the changelog.
Add Unit Tests or Functional Tests for new functionality, refine existing tests if necessary. Tests are important because they ensure that TYPO3 will behave consistently now and in the future.
See Testing the core in TYPO3 Explained for more information about writing and running tests.
Commit your changes
Please make sure that you read the Commit Message rules for TYPO3 CMS in the Appendix. Your code will not be merged if it does not follow the commit message rules.
The section Commit Message rules for TYPO3 CMS is a must-read. Read it. Follow it.
For a bugfix, your commit message may look something like this:
[BUGFIX] Subject line of max 52 chars Some descriptions with line length of max. 72 characters Resolves: #12346 Releases: master, 10.4
Only create one commit. Do not create a branch. Work on master.
git commit -a
The commit-msg hook will do some sanity checks and add a line starting with
If you have activated the pre-commit hook it will loudly complain if something does not conform to the coding guidelines.
After you have created your commit, you can still make changes by amending to your commit:
git commit -a --amend
Keep in mind that you can commit with –amend as often as you want, just make sure you keep the
Push to Gerrit
To submit the patch to Gerrit, issue the following command:
git push origin HEAD:refs/for/master
If you have setup the default as described in Setting up Your Remote it is sufficient to use:
In case you want to push a “Work in progress”, check out: Workflow - work in progress.
If Gerrit accepts your push, it responds with the following messages:
remote: New Changes: remote: https://review.typo3.org/<gerrit-id> remote: To ssh://<username>@review.typo3.org:29418/Packages/TYPO3.CMS.git * [new branch] HEAD -> refs/for/<release-branch>
If you see an error, check out the Git Troubleshooting section.
You can visit the link to https://review.typo3.org to see your patch in Gerrit.
If the automatically starting pre-merge build fails due to an error on Bamboo which isn’t caused by your patch (e.g. time out) you can restart it on Intercept.
Advanced users / core team only: See cheat sheet: other branches for pushing to other branches.
Optional: Use Botty on Slack and wait for reviews
Once your push to Gerrit goes through, you will receive a URL for your new change. If you are on Slack you can now advertise your new change in the #typo3-cms-coredev channel. You can get a preformatted line of your change to post in the channel by clicking the copy button next to the title in Gerrit:
This is not something, you will do for every review. As a first contributor it is recommended to mention that you are new to the process.
Now, it’s time to sit back and await feedback on your changes. The review team process dozens of requests each day, so expect a succinct response that is short and to the point. You will get notified by email, if there is activity on your patch in Gerrit (e.g. votes, comments, new patchsets, merge etc.).
It is not unusual for a patch to get comments requesting changes. If that happens, please respond in a timely fashion and improve your review. If things are unclear, ask in the #typo3-cms-coredev channel on https://typo3.slack.com.
Look at the page Aliases & Git Aliases for some sample aliases which might help to simplify your workflow in the future.
You will find some more information about the review process in the chapter Handle and Improve a Patch (Gerrit). The following pages are especially relevant for new contributors:
- Tips for new contributors
- Introduction to Gerrit describes the review tool Gerrit.
- Find a review on Gerrit is helpful if you don’t know how to find your patch on Gerrit.
- Gerrit works with up- and downvoting patches. A patch must get a specific number of upvotes before it can be merged. Code Review gives an introduction to how this works.
- When you make additional changes to your patch, make sure you do not add another commit. Append to your original commit instead as described in Upload a new Patch Set.
- Before starting to work on a new, unrelated patch you need to run the Cleanup tasks.