Create & submit a patch

Quick links:

So you want to fix a bug or add a new feature to TYPO3? Great!

This chapter will guide you through the process step by step. If you should encounter any problems or have questions, talk to us on in the #typo3-cms-coredev channel (for more information on Slack, see Slack).


We assume, you have followed all steps in the intro & setup chapters.If not, use Quick start: Creating a patch to guide you through the entire process.

Also, an issue must exist for the patch you want to create. Every patch must refer to at least one corresponding issue. If there is no issue yet, create one now by going to (see Create an issue for more information).

Step by step walkthrough

  1. Make your changes to the code

    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.

  2. Add tests

    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 Writing unit tests in TYPO3 Explained for more information about writing Unit Tests.

  3. Optional: Run tests

    See Testing the core for a step-by-step guide using docker.

  4. Add documentation

    For new features, breaking changes and deprecations, it is necessary to add information to the changelog.

  5. Use the commit message rules

    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, 8.7
  6. Commit

    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 Change-Id:.

    If you have activated the pre-commit hook it will loudly complain if something does not conform to the coding guidelines.

    In that case, use the cglFixMyCommit script to to fix CGL issues (it uses php-cs-fixer).

    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 Change-Id: line intact.

  7. Optional: Check your commit history

    Before you submit your patch for review, check what you are going to push:

    git log origin/master..HEAD

    You must only see one commit (for the basic workflow described in this guide).

  8. Push to Gerrit

    To submit the patch to Gerrit, issue the following command:

    git push origin HEAD:refs/for/master

    If Gerrit accepts your push, it responds with the following messages:

    remote: New Changes:
    To ssh://<username>
     * [new branch]      HEAD -> refs/for/<release-branch>

    You can visit the link to to see your patch in Gerrit.

    Advanced users / core team only: See cheat sheet: other branches for pushing to other branches.

  9. 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 using the command:

    review:show [ReviewNumber or URL]

    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

When you change your patch, make sure you do not add another commit. Append to your original commit instead as described in Upload a new Patch Set.


Look at the page Aliases & Git Aliases for some sample aliases which might help to simplify your workflow.

More information