Merge pull request #193 from mattpolzin/feature/189/use-issue-for-pr-description

Populate PR descriptions with GitHub issue context when available

Author: mattpolzin

README.md

@@ -1,4 +1,4 @@
-% harmony(1) Version 5.6.0 | Harmony User's Guide
+% harmony(1) Version 5.7.0 | Harmony User's Guide
 
 # NAME
 Harmony - Harmonize with coworkers around GitHub reviewing
@@ -312,7 +312,7 @@ organization.
 
 Running `harmony list <team>` will list the members of the given GitHub Team.
 
-## `pr [--draft] [#label, ...]`
+## `pr [--draft] [-i/--into {<branch-name>}] [#label, ...]`
 With a branch checked out will reach out to GitHub to determine if there is an
 open PR for that branch. If there is a PR, Harmony will print a URI that can be
 used to view the PR. If there is not a PR, Harmony will help you create one. New
@@ -328,6 +328,14 @@ editor. If you do not have an `EDITOR` environment variable set, you will still
 be able to enter a description from the command line but PR templates are only
 supported when an `EDITOR` is specified.
 
+If you are creating a new PR from a branch that refers to a GitHub issue (and
+you have GitHub branch parsing enabled in your harmony config) then harmony will
+prepend the issue information onto your new PR description in a commented out
+block for you to reference or copy into the PR description as needed.
+
+You can specify the branch to merge into via the `--into` CLI argument if you
+want to as an alternative to the interactive prompt.
+
 You can also specify any number of labels to apply by prefixing them with '#'.
 For example, `harmony pr #backport #bugfix` would create a PR and apply the
 `backport` and `bugfix` labels.
@@ -351,6 +359,12 @@ Create a PR for the current branch and add the `urgent` label:
 harmony pr #urgent
 ```
 
+Create a pull request that will merge into the hypothetical pre-existing
+`release/2_0` branch:
+```shell
+harmony pr --into release/2_0
+```
+
 ## `quick [--bugfix]`
 Helps you create a new GitHub issue and a branch to work on that issue all in
 one go. The branch name will be structured such that if you have GitHub branch

default.nix

@@ -27,7 +27,7 @@ let
   nodeDependencies = buildNpmPackage {
     name = "harmony-npm-deps";
     src = ./.;
-    npmDepsHash = "sha256-jfMZ3ayRV4gNAMdDvPsr4zkPPIM5hb/Mw/Wg00cWXr0=";
+    npmDepsHash = "sha256-ZVHA0Qr6FPliGTOJ4TZTXVxAOwmg+Z55+kKd7Z1RAyA=";
     dontNpmBuild = true;
     dontBuild = true;
 

flake.lock

@@ -1,5 +1,5 @@
 package harmony
-version = 5.6.0
+version = 5.7.0
 authors = "Mathew Polzin"
 license = "MIT"
 brief = "Harmony GitHub collaboration tool"

harmony.ipkg

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.7.0.2
 .\"
-.TH "harmony" "1" "" "Version 5.6.0" "Harmony User\(cqs Guide"
+.TH "harmony" "1" "" "Version 5.7.0" "Harmony User\(cqs Guide"
 .SH NAME
 Harmony \- Harmonize with coworkers around GitHub reviewing
 .SH SYNOPSIS
@@ -380,7 +380,7 @@ configured GitHub organization.
 .PP
 Running \f[CR]harmony list <team>\f[R] will list the members of the
 given GitHub Team.
-.SS \f[CR]pr [\-\-draft] [#label, ...]\f[R]
+.SS \f[CR]pr [\-\-draft] [\-i/\-\-into {<branch\-name>}] [#label, ...]\f[R]
 With a branch checked out will reach out to GitHub to determine if there
 is an open PR for that branch.
 If there is a PR, Harmony will print a URI that can be used to view the
@@ -401,6 +401,15 @@ If you do not have an \f[CR]EDITOR\f[R] environment variable set, you
 will still be able to enter a description from the command line but PR
 templates are only supported when an \f[CR]EDITOR\f[R] is specified.
 .PP
+If you are creating a new PR from a branch that refers to a GitHub issue
+(and you have GitHub branch parsing enabled in your harmony config) then
+harmony will prepend the issue information onto your new PR description
+in a commented out block for you to reference or copy into the PR
+description as needed.
+.PP
+You can specify the branch to merge into via the \f[CR]\-\-into\f[R] CLI
+argument if you want to as an alternative to the interactive prompt.
+.PP
 You can also specify any number of labels to apply by prefixing them
 with `#'.
 For example, \f[CR]harmony pr #backport #bugfix\f[R] would create a PR
@@ -428,6 +437,13 @@ Create a PR for the current branch and add the \f[CR]urgent\f[R] label:
 .EX
 harmony pr #urgent
 .EE
+.PP
+Create a pull request that will merge into the hypothetical
+pre\-existing \f[CR]release/2_0\f[R] branch:
+.IP
+.EX
+harmony pr \-\-into release/2_0
+.EE
 .SS \f[CR]quick [\-\-bugfix]\f[R]
 Helps you create a new GitHub issue and a branch to work on that issue
 all in one go.

man/harmony.1

@@ -1,6 +1,6 @@
 {
   "name": "@mattpolzin/harmony",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "engines": {
     "node": ">=18.0.0"
   },

package-lock.json

@@ -4,7 +4,7 @@ module AppVersion
 
 export
 appVersion : String
-appVersion = "5.6.0"
+appVersion = "5.7.0"
 
 export
 printVersion : HasIO io => io ()

package.json

@@ -6,6 +6,7 @@ import Data.Config
 import Data.Either
 import Data.Fin.Extra
 import Data.Fuel
+import Data.Issue
 import Data.List
 import Data.List1
 import Data.Nat
@@ -265,39 +266,50 @@ convertPRToDraft @{config} pr = do
   prId <- getPullRequestGraphQlId config.org config.repo pr.number
   markPullRequestDraft prId
 
-parseTitleAndBodyPrefix : Config => (branch : String) -> (String, String)
-parseTitleAndBodyPrefix @{config} branch =
+githubTitleAndBodyPrefix : Config => Octokit => (branch: String) -> Promise' (String, String)
+githubTitleAndBodyPrefix @{config} branch =
+  case issueNumber of
+    Nothing => pure ("", "")
+    Just issue => pure $ 
+      (""
+      , !(issueDescriptionPrefix issue) ++ "\n\n" ++ (relatedToPrefix issue)
+      )
+
+  where
+    issueNumber : Maybe String
+    issueNumber = parseGithubIssueNumber branch
+
+    relatedToPrefix : String -> String
+    relatedToPrefix issue = "Related to #\{issue}"
+
+    issueDescriptionPrefix : String -> Promise' String
+    issueDescriptionPrefix issueNumber = do
+      issue <- getIssue config.org config.repo issueNumber
+      pure """
+        <!--
+        ## GitHub Issue
+        \{issue.title}
+        --
+        \{issue.body}
+        -->
+        """
+
+||| The title prefix is to be prepended to the new PR title.
+||| The body prefix is to be prepended to the new PR body.
+|||
+||| The idea in either case is to pass along the information parsed from the
+||| branch name to GitHub either via the PR's title or part of its body so that
+||| an issue referenced by the branch is tracked in relation to the new PR.
+|||
+||| If a GitHub issue is found, the body of the GitHub issue is also added
+||| (commented out) to the body prefix as additional context.
+getTitleAndBodyPrefix : Config => Octokit => (branch : String) -> Promise' (String, String)
+getTitleAndBodyPrefix @{config} branch =
     case config.branchParsing of
-         Jira   => (fromMaybe "" $ (++ " - ") <$> parseJiraSlug branch, "")
-         --         ^ Jira slugs become a title prefix
-         Github => ("", fromMaybe "" $ ("Related to #" ++) <$> parseGithubIssueNumber branch)
-         --             ^ Github issue numbers become a body prefix
-         None   => ("", "")
-
-namespace TestParseTitlePrefix
-  testJiraTurnedOff : parseTitleAndBodyPrefix @{Data.Config.simpleDefaults}
-                                       "ABCD-1234 - hello" 
-                      === 
-                      ("", "")
-  testJiraTurnedOff = Refl
-
-  -- This one does not reduce very far, but far enough for us to know it is going to parse a Jira prefix if possible
-  testJiraTurnedOn : parseTitleAndBodyPrefix @{({ branchParsing := Jira } Data.Config.simpleDefaults)}
-                                      "ABCD-1234 - hello" 
-                     ===
-                     (fromMaybe (Delay (fromString "")) 
-                                (map (\arg => prim__strAppend arg " - ") 
-                                     (parseJiraSlug "ABCD-1234 - hello")), "")
-  testJiraTurnedOn = Refl
-
-  -- This one does not reduce very far, but far enough for us to know it is going to parse a Jira prefix if possible
-  testGithubTurnedOn : parseTitleAndBodyPrefix @{({ branchParsing := Github } Data.Config.simpleDefaults)}
-                                      "feature/1234/hi" 
-                     ===
-                     ("", fromMaybe (Delay (fromString "")) 
-                                    ((\arg => fromString "Related to #" ++ arg) <$>
-                                        parseGithubIssueNumber (fromString "feature/1234/hi")))
-  testGithubTurnedOn = Refl
+         Jira   => pure (fromMaybe "" $ (++ " - ") <$> parseJiraSlug branch, "")
+         --               ^ Jira slugs become a title prefix
+         Github => githubTitleAndBodyPrefix branch
+         None   => pure ("", "")
 
 export
 identifyOrCreatePR : Config => Git => Octokit => 
@@ -382,7 +394,7 @@ identifyOrCreatePR @{config} {isDraft} {intoBranch} branch = do
         putStrLn "Creating a new PR for the current branch (\{branch})."
         baseBranch <- getBaseBranch
 
-        let (titlePrefix, bodyPrefix) = parseTitleAndBodyPrefix branch
+        (titlePrefix, bodyPrefix) <- getTitleAndBodyPrefix branch
 
         putStrLn "What would you like the title to be?"
         putStr titlePrefix