1st round of fixes

RELEASE_NOTES.md

@@ -3,8 +3,8 @@
 ## New in git-machete 3.29.0
 
 - added: git config keys `machete.github.prDescriptionIntroStyle` and `machete.gitlab.mrDescriptionIntroStyle`
-- added: ability to turn off PR/MR description intro completely by setting the git config keys to `none` (suggested by @tir38)
-- added: ability to also include downstream PRs/MRs in PR/MR description intro (suggested by @aouaki)
+- added: ability to turn off PR/MR description intro completely by setting the git config key to `none` (suggested by @tir38)
+- added: ability to include downstream PRs/MRs in PR/MR description intro by setting the git config key to `full` (suggested by @aouaki)
 - changed: layout and ordering of PRs/MRs in PR/MR description intro to better match `git machete status`
 
 ## New in git-machete 3.28.0

ci/checks/prohibit-github-in-gitlab-files.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -e -o pipefail -u
+
+if git grep -E -i -n -e 'github' --and --not -e 'report this error|valid GitLab project' -- '*gitlab*' ':!**/prohibit-*-in-*-files.sh'; then
+  echo
+  echo 'Stray usage of `github` in GitLab-related file(s), is it a copy-paste error?'
+  exit 1
+fi

ci/checks/prohibit-gitlab-in-github-files.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -e -o pipefail -u
+
+if git grep -E -i -n -e 'gitlab' --and --not -e 'valid GitHub repo' -- '*github*' ':!**/prohibit-*-in-*-files.sh'; then
+  echo
+  echo 'Stray usage of `gitlab` in GitHub-related file(s), is it a copy-paste error?'
+  exit 1
+fi

ci/checks/run-all-checks.sh

@@ -31,6 +31,8 @@ prohibit-exempli-gratia-in-rst.sh
 prohibit-fork-point-in-git-context.sh
 prohibit-id-est-in-rst.sh
 prohibit-double-backticks-in-python.sh
+prohibit-github-in-gitlab-files.sh
+prohibit-gitlab-in-github-files.sh
 prohibit-markdown-links-in-rst.sh
 prohibit-mrs-in-github-files.sh
 prohibit-prs-in-gitlab-files.sh

docs/man/git-machete.1

@@ -361,10 +361,18 @@ Setting this config key to \fBtrue\fP will force \fBgit machete github create\-p
 from the message body of the first unique commit of the branch, even if \fB\&.git/info/description\fP and/or \fB\&.github/pull_request_template.md\fP is present.
 .TP
 .B \fBmachete.github.prDescriptionIntroStyle\fP:
-Select the style of the intro prepended to PR description:
-* \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
-* \fBup\-only\fP \-\-\- default, include only a chain of upstream PRs
-* \fBnone\fP    \-\-\- prepend no intro to the PR description at all
+.INDENT 7.0
+.TP
+.B Select the style of the intro prepended to 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
+.IP \(bu 2
+\fBup\-only\fP \-\-\- default, include only a chain of upstream PRs
+.IP \(bu 2
+\fBnone\fP    \-\-\- prepend no intro to the PR description at all
+.UNINDENT
+.UNINDENT
 .TP
 .B \fBmachete.gitlab.{domain,remote,namespace,project}\fP:
 .INDENT 7.0
@@ -399,10 +407,18 @@ Setting this config key to \fBtrue\fP will force \fBgit machete gitlab create\-m
 from the message body of the first unique commit of the branch, even if \fB\&.git/info/description\fP and/or \fB\&.gitlab/merge_request_templates/Default.md\fP is present.
 .TP
 .B \fBmachete.gitlab.mrDescriptionIntroStyle\fP:
-Select the style of the intro prepended to MR description:
-* \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
-* \fBup\-only\fP \-\-\- default, include only a chain of upstream MRs
-* \fBnone\fP    \-\-\- prepend no intro to the MR description at all
+.INDENT 7.0
+.TP
+.B Select the style of the intro prepended to 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
+.IP \(bu 2
+\fBup\-only\fP \-\-\- default, include only a chain of upstream MRs
+.IP \(bu 2
+\fBnone\fP    \-\-\- prepend no intro to the MR description at all
+.UNINDENT
+.UNINDENT
 .TP
 .B \fBmachete.overrideForkPoint.<branch>.to\fP:
 Executing \fBgit machete fork\-point \-\-override\-to[\-parent|\-inferred|=<revision>] [<branch>]\fP sets up a fork point override for \fB<branch>\fP\&.
@@ -1024,7 +1040,7 @@ Sets the base of the current (or specified) branch\(aqs PR to upstream (parent)
 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.
 .sp
-This header will be updated or removed accordingly with the subsequent runs of \fBretarget\-pr\fP, even if the base branch is already up to date.
+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
 \fBOptions:\fP
 .INDENT 7.0
@@ -1089,10 +1105,18 @@ Setting this config key to \fBtrue\fP will force \fBgit machete github create\-p
 from the message body of the first unique commit of the branch, even if \fB\&.git/info/description\fP and/or \fB\&.github/pull_request_template.md\fP is present.
 .TP
 .B \fBmachete.github.prDescriptionIntroStyle\fP (\fBcreate\-pr\fP, \fBrestack\-pr\fP and \fBretarget\-pr\fP):
-Select the style of the intro prepended to PR description:
-* \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
-* \fBup\-only\fP \-\-\- default, include only a chain of upstream PRs
-* \fBnone\fP    \-\-\- prepend no intro to the PR description at all
+.INDENT 7.0
+.TP
+.B Select the style of the intro prepended to 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
+.IP \(bu 2
+\fBup\-only\fP \-\-\- default, include only a chain of upstream PRs
+.IP \(bu 2
+\fBnone\fP    \-\-\- prepend no intro to the PR description at all
+.UNINDENT
+.UNINDENT
 .UNINDENT
 .sp
 \fBEnvironment variables (all subcommands):\fP
@@ -1254,7 +1278,7 @@ Sets the target of the current (or specified) branch\(aqs MR to upstream (parent
 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.
 .sp
-This header will be updated or removed accordingly with the subsequent runs of \fBretarget\-mr\fP, even if the target branch is already up to date.
+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
 \fBOptions:\fP
 .INDENT 7.0
@@ -1305,10 +1329,18 @@ Setting this config key to \fBtrue\fP will force \fBgit machete gitlab create\-m
 from the message body of the first unique commit of the branch, even if \fB\&.git/info/description\fP and/or \fB\&.gitlab/merge_request_templates/Default.md\fP is present.
 .TP
 .B \fBmachete.gitlab.mrDescriptionIntroStyle\fP (\fBcreate\-mr\fP, \fBrestack\-mr\fP and \fBretarget\-mr\fP):
-Select the style of the intro prepended to PR description:
-* \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
-* \fBup\-only\fP \-\-\- default, include only a chain of upstream PRs
-* \fBnone\fP    \-\-\- prepend no intro to the PR description at all
+.INDENT 7.0
+.TP
+.B Select the style of the intro prepended to 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
+.IP \(bu 2
+\fBup\-only\fP \-\-\- default, include only a chain of upstream MRs
+.IP \(bu 2
+\fBnone\fP    \-\-\- prepend no intro to the MR description at all
+.UNINDENT
+.UNINDENT
 .UNINDENT
 .sp
 \fBEnvironment variables (all subcommands):\fP

docs/source/cli/github.rst

@@ -115,7 +115,7 @@ Creates, checks out and manages GitHub PRs while keeping them reflected in branc
     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.
 
-    This header will be updated or removed accordingly with the subsequent runs of ``retarget-pr``, even if the base branch is already up to date.
+    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.
 
     **Options:**
 

docs/source/cli/gitlab.rst

@@ -116,7 +116,7 @@ Creates, checks out and manages GitLab MRs while keeping them reflected in branc
     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.
 
-    This header will be updated or removed accordingly with the subsequent runs of ``retarget-mr``, even if the target branch is already up to date.
+    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.
 
     **Options:**
 
@@ -136,7 +136,7 @@ Creates, checks out and manages GitLab MRs while keeping them reflected in branc
   .. include:: git-config-keys/gitlab_forceDescriptionFromCommitMessage.rst
 
 ``machete.gitlab.mrDescriptionIntroStyle`` (``create-mr``, ``restack-mr`` and ``retarget-mr``):
-  .. include:: git-config-keys/github_prDescriptionIntroStyle.rst
+  .. include:: git-config-keys/gitlab_mrDescriptionIntroStyle.rst
 
 **Environment variables (all subcommands):**
 

docs/source/git-config-keys/github_prDescriptionIntroStyle.rst

@@ -1,4 +1,4 @@
 Select the style of the intro prepended to 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
+  * ``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

docs/source/git-config-keys/gitlab_mrDescriptionIntroStyle.rst

@@ -1,4 +1,4 @@
 Select the style of the intro prepended to 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
+  * ``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

git_machete/client.py

@@ -2260,7 +2260,7 @@ def checkout_pull_requests(self,
     @staticmethod
     def __get_downwards_tree_excluding_pr(original_pr: PullRequest,
                                           all_open_prs: List[PullRequest]) -> List[Tuple[PullRequest, int]]:
-        """Returns pairs of (PR, level below the given PR)"""
+        """Returns pairs of (PR, depth below the given PR)"""
 
         visited_head_branches: Set[str] = set([])
 
@@ -2631,11 +2631,9 @@ def __generate_pr_description_intro(self, code_hosting_client: CodeHostingClient
 
         # For determining the PR chain, we need to fetch all PRs from the repo.
         # We could just fetch them straight away... but this list can be quite long for commercial monorepos,
-        # esp. given that GitHub and GitLab limit the single page to 100 PRs (so multiple HTTP requests may be needed).
+        # esp. given that GitHub and GitLab limit the single page to 100 PRs/MRs (so multiple HTTP requests may be needed).
         # As a slight optimization, in the default UP_ONLY style,
         # let's fetch the full PR list only if the current PR has a base PR at all.
-        # In FULL style, we need to check for downstream PRs as well, so the full PR list needs to be fetched anyway.
-        # That's also the performance reason behind selecting UP_ONLY and not FULL as the default style.
         prs_for_base_branch = code_hosting_client.get_open_pull_requests_by_head(LocalBranchShortName(pr.base))
         if style == PRDescriptionIntroStyle.UP_ONLY and len(prs_for_base_branch) == 0:
             return ''

git_machete/generated_docs.py

@@ -250,10 +250,14 @@
               from the message body of the first unique commit of the branch, even if `.git/info/description` and/or `.github/pull_request_template.md` is present.
 
            `machete.github.prDescriptionIntroStyle`:
-              Select the style of the intro prepended to 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
+
+                 Select the style of the intro prepended to 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
 
            `machete.gitlab.{domain,remote,namespace,project}`:
 
@@ -283,10 +287,14 @@
               from the message body of the first unique commit of the branch, even if `.git/info/description` and/or `.gitlab/merge_request_templates/Default.md` is present.
 
            `machete.gitlab.mrDescriptionIntroStyle`:
-              Select the style of the intro prepended to 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
+
+                 Select the style of the intro prepended to 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
 
            `machete.overrideForkPoint.<branch>.to`:
  
@@ -671,7 +679,7 @@
               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.
 
-              This header will be updated or removed accordingly with the subsequent runs of `retarget-pr`, even if the base branch is already up to date.
+              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.
 
               <b>Options:</b>
 
@@ -728,10 +736,14 @@
               from the message body of the first unique commit of the branch, even if `.git/info/description` and/or `.github/pull_request_template.md` is present.
 
            `machete.github.prDescriptionIntroStyle` (`create-pr`, `restack-pr` and `retarget-pr`):
-              Select the style of the intro prepended to 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
+
+                 Select the style of the intro prepended to 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
 
         <b>Environment variables (all subcommands):</b>
            `GITHUB_TOKEN`
@@ -858,7 +870,7 @@
               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.
 
-              This header will be updated or removed accordingly with the subsequent runs of `retarget-mr`, even if the target branch is already up to date.
+              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.
 
               <b>Options:</b>
 
@@ -902,10 +914,14 @@
               from the message body of the first unique commit of the branch, even if `.git/info/description` and/or `.gitlab/merge_request_templates/Default.md` is present.
 
            `machete.gitlab.mrDescriptionIntroStyle` (`create-mr`, `restack-mr` and `retarget-mr`):
-              Select the style of the intro prepended to 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
+
+                 Select the style of the intro prepended to 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
 
         <b>Environment variables (all subcommands):</b>
            `GITLAB_TOKEN`

git_machete/github.py

@@ -248,7 +248,7 @@ def __fire_github_api_request(self, method: str, path: str, request_body: Option
                          "Skipped adding reviewers to the pull request.")
                 else:
                     raise UnexpectedMacheteException(
-                        f'GitLab API returned 422 (Unprocessable Entity) HTTP status with error message: `{error_reason}`.')
+                        f'GitHub API returned 422 (Unprocessable Entity) HTTP status with error message: `{error_reason}`.')
             elif err.code in (http.HTTPStatus.UNAUTHORIZED, http.HTTPStatus.FORBIDDEN):
                 first_line = f'GitHub API returned `{err.code}` HTTP status with error message: `{err.reason}`\n'
                 last_line = 'You can also use a different token provider - see `git machete help github` for details.'