docs: update releasehotfix doc

docs/HotFixGuide.md

@@ -0,0 +1,73 @@
+# HotFix Guide
+
+## HotFix general instructions
+
+The following instructions intend to be general case for applying hotfixes in
+release branches, for more specific cases, simplified instructions are to be
+found in the below sub-sections.
+
+1. Find the oldest relevant release branch BASE to which this hotfix applies.
+   - Relevant release branches include: release, and release-specific
+     maintained branches.
+2. Create a hotfix branch branching from BASE.
+   - if the hotfix branch already exists `git rebase --onto BASE`.
+3. Open a merge-request targeting:
+   - master, if applies to master.
+   - Otherwise, release, if applies to the latest release.
+   - Otherwise, the most recent release-specific branch to which this hotfix
+     applies.
+   - Lastly, if none of above, BASE.
+4. At the bottom of the description of the merge-request add: `Backport: branch_name`
+   directive for each of the branches that exists between BASE (inclusive) and
+   the branch that we target our merge-request (exclusive).
+
+In the case of merge conflicts in any of the backports refer to [Kitware backport guide][1].
+
+## HotFix for latest release and master branch only
+
+For hotfixes that applies to release and master branch, create a branch based
+off of the tip of the release branch and create a merge-request targeting master.
+
+If the hotfix branch already exists based off of a commit in the master branch,
+you can change the base branch of the hotfix branch from master to latest
+release with:
+
+```
+# Assuming that both your local master and release branch are updated; and
+# assuming that you are currently in your topic branch
+
+git rebase --onto release master
+```
+
+Next, you can bring this commit to __release__ by adding the following line to
+the bottom of the MR description: `Backport: release`. This directive will later
+internally instruct the Kitware Robot to bring the changes of the hotfix branch
+creating a merge commit in the release branch with its second parent being the
+hotfix branch tip.
+
+Lastly, the master branch history will be automatically connected with
+release after the merge-request is merged as explained in
+[here](#How-master-and-release-branch-are-connected).
+
+## HotFix for release branch only
+
+For hotfixes that only applies to release branch, whose changes are unneeded in
+master, create a branch based off of the __release__ branch and create a
+merge-request targeting __release__ branch. Proceed as in a regular MR.
+
+### How master and release branch are connected
+
+Every merge commit in the release branch will be automatically connected to
+master branch by our Gitlab robot creating a merge-request using the
+`-s ours` strategy, __note__ that `-s ours` strategy does not actually bring any
+change to the target branch, it will solely create an empty merge commit in master
+connecting release branch..
+
+
+## Other cases
+
+There are more possible case scenarios that you might encounter while attempting
+to bring a hotfix to release, for further cases please refer to the
+[Kitware backport guide][1] which this document is based of.
+
+[1]: https://gitlab.kitware.com/utils/git-workflow/-/wikis/Backport-topics

docs/ReleaseHotFix.md

@@ -1,55 +0,0 @@
-Release HotFix
-===============
-
-# HotFix from master branch
-
-## On a single MR
-
-You have created a branch from master branch and you have a MR request targeting
-the __master__ branch.
-
-You can bring this commit to __release__ by adding the following line to
-the bottom of the MR description.
-
-```
-Backport: release
-```
-
-This will cherry-pick this commit and push it to __release__ after typing `Do:
-merge` in a comment.
-
-You must also make sure that there will not be any merge conflict with the 
-__release__ branch, thus you need to create an additional commit using the following
-command:
-
-```
-git merge --no-ff origin/release
-```
-
-This will ensure that backport will be able to push your commit to __release__.
-
-## On multiple MRs
-
-1. Create one merge request sourcing your HotFix branch and targeting __master__
-and merge.
-
-2. Create one merge request sourcing __master__ and targeting __release__ and merge.
-
-# HotFix from release branch
-
-You have created a branch from the __release__ branch and you have a MR request
-targeting __release__, you can proceed as in a regular MR.
-
-Every merge in release will be automatically brought to master by the robot
-using `-s ours` strategy. 
-
-__VERY IMPORTANT__: `-s ours` strategy does not actually bring any change to the 
-target branch, thus if needed you might want to bring the changes
-from the HotFix to __master__ by creating a another MR which cherry-picks
-the merge commit in `release` for the given HotFix.
-
-Use the difference to first parent for the cherry-pick commit:
-
-```
-git cherry-pick -m1 -x <HASH OF COMMIT>
-```