Make create-{pr,mr} take the existing `<!-- {start,end} git-machete…

… generated -->` markers into account
VirtusLab · Sep 18, 2024 · c7da79c · c7da79c
1 parent 08df355
commit c7da79c
Show file tree

Hide file tree

Showing 12 changed files with 85 additions and 68 deletions.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -3,7 +3,8 @@
 ## New in git-machete 3.29.3
 
 - changed: no longer publish RPM files with GitHub releases
-- fixed: work around the parsing bug in `git patch-id` v2.46.1
+- fixed: work around the parsing bug in `git patch-id` v2.46.1 (reported by @ilai-deutel)
+- fixed: `git machete git{hub,lab} create-{pr,mr}` takes into account `<!-- {start,end} git-machete generated -->` in PR/MR template (suggested by @frank-west-iii)
 
 ## New in git-machete 3.29.2
 

diff --git a/docs/man/git-machete.1 b/docs/man/git-machete.1
@@ -363,7 +363,7 @@ from the message body of the first unique commit of the branch, even if \fB\&.gi
 .B \fBmachete.github.prDescriptionIntroStyle\fP:
 .INDENT 7.0
 .TP
-.B Select the style of the intro prepended to PR description:
+.B Select the style of the generated section (\(dqintro\(dq) added to the PR description:
 .INDENT 7.0
 .IP \(bu 2
 \fBfull\fP    \-\-\- include both a chain of upstream PRs (typically leading to \fBmain\fP, \fBmaster\fP, \fBdevelop\fP etc.) and a tree of downstream PRs
@@ -409,7 +409,7 @@ from the message body of the first unique commit of the branch, even if \fB\&.gi
 .B \fBmachete.gitlab.mrDescriptionIntroStyle\fP:
 .INDENT 7.0
 .TP
-.B Select the style of the intro prepended to MR description:
+.B Select the style of the generated section (\(dqintro\(dq) added to the MR description:
 .INDENT 7.0
 .IP \(bu 2
 \fBfull\fP    \-\-\- include both a chain of upstream MRs (typically leading to \fBmain\fP, \fBmaster\fP, \fBdevelop\fP etc.) and a tree of downstream MRs
@@ -999,11 +999,13 @@ If \fB\&.git/info/milestone\fP file is present, its contents (a single number \-
 If \fB\&.git/info/reviewers\fP file is present, its contents (one GitHub login per line) are used to set reviewers.
 .sp
 The subject of the first unique commit of the branch is used as PR title.
-If \fB\&.git/info/description\fP or \fB\&.github/pull_request_template.md\fP file is present, its contents are used as PR description.
+If \fB\&.git/info/description\fP or \fB\&.github/pull_request_template.md\fP template is present, its contents are used as PR description.
 Otherwise (or if \fBmachete.github.forceDescriptionFromCommitMessage\fP is set), PR description is taken from message body of the first unique commit of the branch.
 .sp
-If the newly\-created PR is stacked atop another PR, the actual PR description posted to GitHub will be prepended with a section
-listing the entire related chain of PRs.
+If the newly\-created PR is stacked atop another PR, the actual PR description posted to GitHub will include a generated section (\(dqintro\(dq)
+listing the entire related chain of PRs. This section will be delimited with \fB<!\-\- start git\-machete generated \-\->\fP
+and \fB<!\-\- end git\-machete generated \-\->\fP comments in Markdown. If a PR template file exists and contains these comments already,
+the generated section will be placed between them; otherwise, it will be placed at the beginning.
 .sp
 \fBOptions:\fP
 .INDENT 7.0
@@ -1037,8 +1039,8 @@ Draft PRs don\(aqt get code owners automatically added as reviewers.
 .B \fBretarget\-pr [\-b|\-\-branch=<branch>] [\-\-ignore\-if\-missing]\fP:
 Sets the base of the current (or specified) branch\(aqs PR to upstream (parent) branch, as seen by git machete (see \fBgit machete show up\fP).
 .sp
-If after changing the base the PR ends up stacked atop another PR, the PR description posted to GitHub will be prepended
-with an intro section listing the entire related chain of PRs.
+If after changing the base the PR ends up stacked atop another PR, the PR description posted to GitHub will include
+a generated section (\(dqintro\(dq) listing the entire related chain of PRs.
 .sp
 This intro will be updated or removed accordingly with the subsequent runs of \fBretarget\-pr\fP, even if the base branch is already up to date.
 .sp
@@ -1107,7 +1109,7 @@ from the message body of the first unique commit of the branch, even if \fB\&.gi
 .B \fBmachete.github.prDescriptionIntroStyle\fP (\fBcreate\-pr\fP, \fBrestack\-pr\fP and \fBretarget\-pr\fP):
 .INDENT 7.0
 .TP
-.B Select the style of the intro prepended to PR description:
+.B Select the style of the generated section (\(dqintro\(dq) added to the PR description:
 .INDENT 7.0
 .IP \(bu 2
 \fBfull\fP    \-\-\- include both a chain of upstream PRs (typically leading to \fBmain\fP, \fBmaster\fP, \fBdevelop\fP etc.) and a tree of downstream PRs
@@ -1237,11 +1239,13 @@ Note that you need to use a global (not per\-project) milestone id. Look for som
 If \fB\&.git/info/reviewers\fP file is present, its contents (one GitLab login per line) are used to set reviewers.
 .sp
 The subject of the first unique commit of the branch is used as MR title.
-If \fB\&.git/info/description\fP or \fB\&.gitlab/merge_request_templates/Default.md\fP file is present, its contents are used as MR description.
+If \fB\&.git/info/description\fP or \fB\&.gitlab/merge_request_templates/Default.md\fP template is present, its contents are used as MR description.
 Otherwise (or if \fBmachete.gitlab.forceDescriptionFromCommitMessage\fP is set), MR description is taken from message body of the first unique commit of the branch.
 .sp
-If the newly\-created MR is stacked atop another MR, the actual MR description posted to GitLab will be prepended with a section
-listing the entire related chain of MRs.
+If the newly\-created MR is stacked atop another MR, the actual MR description posted to GitLab will include a generated section (\(dqintro\(dq)
+listing the entire related chain of MRs. This section will be delimited with \fB<!\-\- start git\-machete generated \-\->\fP
+and \fB<!\-\- end git\-machete generated \-\->\fP comments in Markdown. If an MR template file exists and contains these comments already,
+the generated section will be placed between them; otherwise, it will be placed at the beginning.
 .sp
 \fBOptions:\fP
 .INDENT 7.0
@@ -1275,8 +1279,8 @@ Draft MRs don\(aqt get code owners automatically added as reviewers.
 .B \fBretarget\-mr [\-b|\-\-branch=<branch>] [\-\-ignore\-if\-missing]\fP:
 Sets the target of the current (or specified) branch\(aqs MR to upstream (parent) branch, as seen by git machete (see \fBgit machete show up\fP).
 .sp
-If after changing the target the MR ends up stacked atop another MR, the MR description posted to GitLab will be prepended
-with an intro section listing the entire related chain of MRs.
+If after changing the base the MR ends up stacked atop another MR, the MR description posted to GitLab will include
+a generated section (\(dqintro\(dq) listing the entire related chain of MRs.
 .sp
 This intro will be updated or removed accordingly with the subsequent runs of \fBretarget\-mr\fP, even if the target branch is already up to date.
 .sp
@@ -1331,7 +1335,7 @@ from the message body of the first unique commit of the branch, even if \fB\&.gi
 .B \fBmachete.gitlab.mrDescriptionIntroStyle\fP (\fBcreate\-mr\fP, \fBrestack\-mr\fP and \fBretarget\-mr\fP):
 .INDENT 7.0
 .TP
-.B Select the style of the intro prepended to MR description:
+.B Select the style of the generated section (\(dqintro\(dq) added to the MR description:
 .INDENT 7.0
 .IP \(bu 2
 \fBfull\fP    \-\-\- include both a chain of upstream MRs (typically leading to \fBmain\fP, \fBmaster\fP, \fBdevelop\fP etc.) and a tree of downstream MRs

diff --git a/docs/source/cli/github.rst b/docs/source/cli/github.rst
@@ -84,11 +84,13 @@ Creates, checks out and manages GitHub PRs while keeping them reflected in branc
     If ``.git/info/reviewers`` file is present, its contents (one GitHub login per line) are used to set reviewers.
 
     The subject of the first unique commit of the branch is used as PR title.
-    If ``.git/info/description`` or ``.github/pull_request_template.md`` file is present, its contents are used as PR description.
+    If ``.git/info/description`` or ``.github/pull_request_template.md`` template is present, its contents are used as PR description.
     Otherwise (or if ``machete.github.forceDescriptionFromCommitMessage`` is set), PR description is taken from message body of the first unique commit of the branch.
 
-    If the newly-created PR is stacked atop another PR, the actual PR description posted to GitHub will be prepended with a section
-    listing the entire related chain of PRs.
+    If the newly-created PR is stacked atop another PR, the actual PR description posted to GitHub will include a generated section ("intro")
+    listing the entire related chain of PRs. This section will be delimited with ``<!-- start git-machete generated -->``
+    and ``<!-- end git-machete generated -->`` comments in Markdown. If a PR template file exists and contains these comments already,
+    the generated section will be placed between them; otherwise, it will be placed at the beginning.
 
     **Options:**
 
@@ -112,8 +114,8 @@ Creates, checks out and manages GitHub PRs while keeping them reflected in branc
 ``retarget-pr [-b|--branch=<branch>] [--ignore-if-missing]``:
     Sets the base of the current (or specified) branch's PR to upstream (parent) branch, as seen by git machete (see ``git machete show up``).
 
-    If after changing the base the PR ends up stacked atop another PR, the PR description posted to GitHub will be prepended
-    with an intro section listing the entire related chain of PRs.
+    If after changing the base the PR ends up stacked atop another PR, the PR description posted to GitHub will include
+    a generated section ("intro") listing the entire related chain of PRs.
 
     This intro will be updated or removed accordingly with the subsequent runs of ``retarget-pr``, even if the base branch is already up to date.
 

diff --git a/docs/source/cli/gitlab.rst b/docs/source/cli/gitlab.rst
@@ -85,11 +85,13 @@ Creates, checks out and manages GitLab MRs while keeping them reflected in branc
     If ``.git/info/reviewers`` file is present, its contents (one GitLab login per line) are used to set reviewers.
 
     The subject of the first unique commit of the branch is used as MR title.
-    If ``.git/info/description`` or ``.gitlab/merge_request_templates/Default.md`` file is present, its contents are used as MR description.
+    If ``.git/info/description`` or ``.gitlab/merge_request_templates/Default.md`` template is present, its contents are used as MR description.
     Otherwise (or if ``machete.gitlab.forceDescriptionFromCommitMessage`` is set), MR description is taken from message body of the first unique commit of the branch.
 
-    If the newly-created MR is stacked atop another MR, the actual MR description posted to GitLab will be prepended with a section
-    listing the entire related chain of MRs.
+    If the newly-created MR is stacked atop another MR, the actual MR description posted to GitLab will include a generated section ("intro")
+    listing the entire related chain of MRs. This section will be delimited with ``<!-- start git-machete generated -->``
+    and ``<!-- end git-machete generated -->`` comments in Markdown. If an MR template file exists and contains these comments already,
+    the generated section will be placed between them; otherwise, it will be placed at the beginning.
 
     **Options:**
 
@@ -113,8 +115,8 @@ Creates, checks out and manages GitLab MRs while keeping them reflected in branc
 ``retarget-mr [-b|--branch=<branch>] [--ignore-if-missing]``:
     Sets the target of the current (or specified) branch's MR to upstream (parent) branch, as seen by git machete (see ``git machete show up``).
 
-    If after changing the target the MR ends up stacked atop another MR, the MR description posted to GitLab will be prepended
-    with an intro section listing the entire related chain of MRs.
+    If after changing the base the MR ends up stacked atop another MR, the MR description posted to GitLab will include
+    a generated section ("intro") listing the entire related chain of MRs.
 
     This intro will be updated or removed accordingly with the subsequent runs of ``retarget-mr``, even if the target branch is already up to date.
 

diff --git a/docs/source/git-config-keys/github_prDescriptionIntroStyle.rst b/docs/source/git-config-keys/github_prDescriptionIntroStyle.rst
@@ -1,4 +1,4 @@
-Select the style of the intro prepended to PR description:
+Select the style of the generated section ("intro") added to the PR description:
   * ``full``    --- include both a chain of upstream PRs (typically leading to ``main``, ``master``, ``develop`` etc.) and a tree of downstream PRs
   * ``up-only`` --- default, include only a chain of upstream PRs
   * ``none``    --- prepend no intro to the PR description at all
diff --git a/docs/source/git-config-keys/gitlab_mrDescriptionIntroStyle.rst b/docs/source/git-config-keys/gitlab_mrDescriptionIntroStyle.rst
@@ -1,4 +1,4 @@
-Select the style of the intro prepended to MR description:
+Select the style of the generated section ("intro") added to the MR description:
   * ``full``    --- include both a chain of upstream MRs (typically leading to ``main``, ``master``, ``develop`` etc.) and a tree of downstream MRs
   * ``up-only`` --- default, include only a chain of upstream MRs
   * ``none``    --- prepend no intro to the MR description at all
diff --git a/git_machete/client.py b/git_machete/client.py
@@ -2465,11 +2465,12 @@ def skip_leading_empty(strs: List[str]) -> List[str]:
             start_index = lines.index(self.START_GIT_MACHETE_GENERATED_COMMENT)
             end_index = lines.index(self.END_GIT_MACHETE_GENERATED_COMMENT)
             lines = lines[:start_index] + lines_to_prepend + lines[end_index + 1:]
+            lines = skip_leading_empty(lines)
         else:
             # For compatibility with pre-v3.23.0 format; only affects GitHub
             if lines and '# Based on PR #' in lines[0]:
-                lines = skip_leading_empty(lines[1:])
-            lines = lines_to_prepend + lines
+                lines = lines[1:]
+            lines = lines_to_prepend + ([''] if lines_to_prepend else []) + skip_leading_empty(lines)
         return '\n'.join(lines)
 
     def retarget_pr(self, spec: CodeHostingSpec, head: LocalBranchShortName, ignore_if_missing: bool) -> None:
@@ -2792,14 +2793,11 @@ def create_pull_request(
         if base_branch_found_on_remote or style == PRDescriptionIntroStyle.FULL:
             # As the description may include the reference to this PR itself (in case of a chain of >=2 PRs),
             # let's update the PR description after it's already created (so that we know the current PR's number).
-            text_to_prepend = self.__generate_pr_description_intro(code_hosting_client, pr, style)
-            if text_to_prepend:
-                if description:
-                    text_to_prepend += '\n'
-                description = text_to_prepend + description
+            new_description = self.__get_updated_pull_request_description(code_hosting_client, pr, description)
+            if new_description.strip() != description.strip():
                 print(f'Updating description of {pr.display_text()} to include '
                       f'the chain of {spec.pr_short_name}s... ', end='', flush=True)
-                code_hosting_client.set_description_of_pull_request(pr.number, description)
+                code_hosting_client.set_description_of_pull_request(pr.number, new_description)
                 print(fmt(ok_str))
 
         milestone_path: str = self.__git.get_main_git_subpath('info', 'milestone')