---
title: "Backport changes"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:backport-changes"
source: "Maintainers/BackportChanges.rst"
rendered: "2026-09-23T16:57:04+00:00"
---

# Backport changes {#backport-changes}

Most of the time changes will be made to branch `main` and backported.

When creating a pull request, it is possible to add a `Releases` line in the
commit message (as done in the Core):

```text
Releases: main, 14.3
```

However, this is not enforced and not always done. In any case, it is
up to the user merging a PR to decide how far the changes are to be
backported.

Here are some tips and conventions:

## Community user: what should I do if I found an error in the documentation that applies to several versions? {#backport-changes-community-user-should}

Apply your changes to the latest version you have verified your change
to work with. If it is possible, apply your change to the "main" branch.

Leave a hint about which versions you have tested, for example:

```text
Verified this on 14.3 and 13.4, I suspect it will also still be the case on
main. Could someone verify this please?

Releases: main, 14.3, 13.4
```

See [commit message conventions](https://docs.typo3.org/permalink/h2document:commit-messages) for the full
picture.

The backporting itself will be done by the maintainers of the Documentation Team.
Sometimes automatic backporting is not possible due to changes in the documentation
structure. In such a case, you may be asked, if you would like to provide a pull
request for the back versions.

> [!NOTE]
> Only bugs will be backported more then one version. Improvements, etc may
> only be backported to the latest LTS release.

## Merger: the pull request needs to be backported, what should I do? {#backport-changes-merger-pull-request}

When the pull request needs to be backported, add labels for all needed versions
to the pull request.

Example: If the pull request needs to be backported to version 12.4 and 11.5,
add the corresponding labels **backport 12.4** and
**backport 11.5**. The labels will trigger an automatic backport once
the current pull request is merged or the label is added to an already merged
pull request.

## How do automatic backports work {#backport-changes-automatic-backports-work}

The CI runner will create a separate pull
request for each version that has been labeled - if, and only if, it can do the
cherry-picking into the branch without conflicts.

If the automatic backport is successful, a new pull request will be created for
the backport. This pull request can be approved and merged manually.

If the backport fails, a comment will be added to the original pull request. The
label **backport failed** will be added to the original pull request and
manual cherry-picking is required.

## Up to which version? {#backport-changes-version}

**Convention:** We backport to the newest LTS version unless the changes only
apply to the main version. Major errors and bug may be backported to the
older LTS version.

There may be reasons to do this differently:

-   Decisions about which versions to backport to are at the discretion of the
    user doing the merging.
-   Sometimes too many changes are necessary because of merge conflicts.
    Sometimes, the structure has changed. In this case, decide if it is worth
    the effort.

## How to merge? {#backport-changes-merge}

Using the second option in the green **Merge pull request** button
**Squash and merge** has proven useful for a number of
reasons:

-   This merges everything into one commit which makes it easier
    to cherry-pick.
-   This automatically adds the pull request number into the commit message
    which adds a reference to the original pull request when merging or
    cherry-picking this to another branch. That way the backport process is
    visible in the pull request.

If there are more than one contributor who committed changes, a text about
additional authors is automatically added to the commit.

> [!NOTE]
> **See also**
>
> -   [Configuring commit squashing for pull requests](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/configuring-commit-squashing-for-pull-requests)

## How to backport manually? {#backport-changes-backport-manually}

Please make sure that you are in the branch you have just pushed into.
Preferably `main`:

```shell
git checkout main
```

Look up the commit ID with

```shell
git log
```

Switch to the branch to which you would like to make a backport.
If you cherry-pick a commit locally, you can (optionally) use `-x` to
automatically insert information that this is a cherry-pick and
the original commit ID.

This makes the history clearer.

```shell
git cherry-pick -x <commit-id>
```

This is how the commit might look like:

```shell
Author: Author <email@example.org>
Date:   Fri Jun 26 15:50:08 2023 +0200

    [TASK] Subject

    (cherry picked from commit 609493dd8893cbac7ad78aa38a23e02d011bb0c2)
```

If a merge conflict arises solve the merge conflict within the Git related
files like `rst` and `md`.
For a visual confirmation you can now execute the building process again with:

```shell
make docs
```

If everything looks fine continue the cherry-pick with

```shell
git cherry-pick --continue
```

Push your changes.
Check in the intercept to see if a new rendering has started. Once this is
done, check the documentation to see if the backport worked as expected.