Backport changes 

Community user: what should I do if I found an error in the documentation that applies to several versions? 

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:

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 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.

Merger: the pull request needs to be backported, what should I do? 

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 

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. Merge it by hand, see Merge a backport pull request.

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.

What the backport labels mean 

backport <version>

Asks for a backport to that branch. The label triggers the automatic backport when the pull request is merged, or as soon as it is added to an already merged one.

Never put this label on a pull request against that branch itself. The automatic backport then tries to cherry-pick the change into the same branch again, and the backport fails.

backport-required

A backport is still to be prepared or decided on.

If it is clear beforehand that the backport must be made by hand, put this label on the pull request against main instead of backport <version>. A manual backport is needed, for example, if the content or the screenshots differ between the versions. After the merge, open the backport pull request, see How to backport manually?.

backport-failed

The automatic backport could not cherry-pick the change into that branch. It has to be done by hand, see How to backport manually?.

backport-done

The backport pull requests exist. The automatic backport sets this label as soon as it has created them, and whoever backports by hand sets it as soon as those pull requests are open. In neither case does it mean that they have been merged.

Because of the last one, the labels of a pull request do not tell you whether a change reached a branch. Ask the branch itself:

git fetch origin
git log origin/14.3 --oneline --grep="part of the subject"

Up to which 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? 

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.

diff <(gh pr diff <original> | grep '^[-+]') <(gh pr diff <backport> | grep '^[-+]')

How to backport manually? 

Make the backport after the original pull request has been merged, just like the automatic backport does. Do not open a backport pull request while the original pull request is still open. A review of one of them would not reach the other.

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

git checkout main

Look up the commit ID with:

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.

git cherry-pick -x <commit-id>

This is how the commit might look like:

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:

make docs

If everything looks fine continue the cherry-pick with:

git cherry-pick --continue

Push your changes and open the backport pull request, see Mark the pull request as a backport. 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.

Swap backport-failed or backport-required for backport-done on the original pull request as soon as your backport pull requests are open. The automatic backport labels its own the same way, when it creates them rather than when they are merged.

[Backport 14.3] [FEATURE] Explain what to do when an error page shows

Backport of #364 to `14.3`.