From 4b055e786bc41dbda8ca13ef3287c6cd83575bc9 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 23 Jul 2025 18:23:07 +0000 Subject: [PATCH 01/13] chore(deps): bump github.com/spf13/pflag from 1.0.6 to 1.0.7 Bumps [github.com/spf13/pflag](https://github.com/spf13/pflag) from 1.0.6 to 1.0.7. - [Release notes](https://github.com/spf13/pflag/releases) - [Commits](https://github.com/spf13/pflag/compare/v1.0.6...v1.0.7) --- updated-dependencies: - dependency-name: github.com/spf13/pflag dependency-version: 1.0.7 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- go.mod | 2 +- go.sum | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/go.mod b/go.mod index 7f0569303..5667e998c 100644 --- a/go.mod +++ b/go.mod @@ -47,7 +47,7 @@ require ( github.com/sigstore/protobuf-specs v0.5.0 github.com/sigstore/sigstore-go v1.1.0 github.com/spf13/cobra v1.9.1 - github.com/spf13/pflag v1.0.6 + github.com/spf13/pflag v1.0.7 github.com/stretchr/testify v1.10.0 github.com/theupdateframework/go-tuf/v2 v2.1.1 github.com/yuin/goldmark v1.7.12 diff --git a/go.sum b/go.sum index 5433198cd..cd23474dc 100644 --- a/go.sum +++ b/go.sum @@ -1363,8 +1363,9 @@ github.com/spf13/cast v1.9.2 h1:SsGfm7M8QOFtEzumm7UZrZdLLquNdzFYfIbEXntcFbE= github.com/spf13/cast v1.9.2/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo= github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo= github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0= -github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o= github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= +github.com/spf13/pflag v1.0.7 h1:vN6T9TfwStFPFM5XzjsvmzZkLuaLX+HS+0SeFLRgU6M= +github.com/spf13/pflag v1.0.7/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= github.com/spf13/viper v1.20.1 h1:ZMi+z/lvLyPSCoNtFCpqjy0S4kPbirhpTMwl8BkW9X4= github.com/spf13/viper v1.20.1/go.mod h1:P9Mdzt1zoHIG8m2eZQinpiBjo6kCmZSKBClNNqjJvu4= github.com/spiffe/go-spiffe/v2 v2.5.0 h1:N2I01KCUkv1FAjZXJMwh95KK1ZIQLYbPfhaxw8WS0hE= From 45876eddc290075e4ad148b5028f26b6472b09de Mon Sep 17 00:00:00 2001 From: Sukh Date: Mon, 23 Jun 2025 13:19:37 -0400 Subject: [PATCH 02/13] docs(search): add note for exclusion search syntax --- pkg/cmd/search/code/code.go | 3 +++ pkg/cmd/search/commits/commits.go | 3 +++ pkg/cmd/search/issues/issues.go | 3 +++ pkg/cmd/search/prs/prs.go | 3 +++ pkg/cmd/search/repos/repos.go | 3 +++ 5 files changed, 15 insertions(+) diff --git a/pkg/cmd/search/code/code.go b/pkg/cmd/search/code/code.go index d03526c4d..3a439e5cd 100644 --- a/pkg/cmd/search/code/code.go +++ b/pkg/cmd/search/code/code.go @@ -46,6 +46,9 @@ func NewCmdCode(f *cmdutil.Factory, runF func(*CodeOptions) error) *cobra.Comman Note that these search results are powered by what is now a legacy GitHub code search engine. The results might not match what is seen on %[1]sgithub.com%[1]s, and new features like regex search are not yet available via the GitHub API. + + Note: When using GitHub search syntax to exclude results (e.g. '-language:xml'), you must use + a '--' delimiter before the search query to separate it from command flags. `, "`"), Example: heredoc.Doc(` # Search code matching "react" and "lifecycle" diff --git a/pkg/cmd/search/commits/commits.go b/pkg/cmd/search/commits/commits.go index fb1742dc9..161ecc6a9 100644 --- a/pkg/cmd/search/commits/commits.go +++ b/pkg/cmd/search/commits/commits.go @@ -45,6 +45,9 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra. GitHub search syntax is documented at: + + Note: When using GitHub search syntax to exclude results (e.g. '-user:monalisa'), you must use + a '--' delimiter before the search query to separate it from command flags. `), Example: heredoc.Doc(` # Search commits matching set of keywords "readme" and "typo" diff --git a/pkg/cmd/search/issues/issues.go b/pkg/cmd/search/issues/issues.go index e1f4105ae..af6e9d64c 100644 --- a/pkg/cmd/search/issues/issues.go +++ b/pkg/cmd/search/issues/issues.go @@ -34,6 +34,9 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c GitHub search syntax is documented at: + + Note: When using GitHub search syntax to exclude results (e.g. '-label:bug'), you must use + a '--' delimiter before the search query to separate it from command flags. `), Example: heredoc.Doc(` # Search issues matching set of keywords "readme" and "typo" diff --git a/pkg/cmd/search/prs/prs.go b/pkg/cmd/search/prs/prs.go index f7a96c5bf..b268ea3e5 100644 --- a/pkg/cmd/search/prs/prs.go +++ b/pkg/cmd/search/prs/prs.go @@ -36,6 +36,9 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr GitHub search syntax is documented at: + + Note: When using GitHub search syntax to exclude results (e.g. '-label:bug'), you must use + a '--' delimiter before the search query to separate it from command flags. `), Example: heredoc.Doc(` # Search pull requests matching set of keywords "fix" and "bug" diff --git a/pkg/cmd/search/repos/repos.go b/pkg/cmd/search/repos/repos.go index 2815ee6dc..733d7b7c4 100644 --- a/pkg/cmd/search/repos/repos.go +++ b/pkg/cmd/search/repos/repos.go @@ -46,6 +46,9 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm GitHub search syntax is documented at: + + Note: When using GitHub search syntax to exclude results (e.g. '-topic:linux'), you must use + a '--' delimiter before the search query to separate it from command flags. `), Example: heredoc.Doc(` # Search repositories matching set of keywords "cli" and "shell" From 254119e49880b1dbc6ca2c0fa66c5a6a6d8d346a Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Fri, 25 Jul 2025 17:23:45 -0600 Subject: [PATCH 03/13] Add help topic for search syntax in gh commands Introduces a new help topic explaining how to use exclusion qualifiers in GitHub search syntax with gh commands, including platform-specific instructions for Unix-like systems and PowerShell. Provides links to relevant documentation for further reference. Co-Authored-By: Sid <41968447+sukhpreet-s@users.noreply.github.com> --- pkg/cmd/root/help_topic.go | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index a375d9e20..6ea626e06 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -304,6 +304,35 @@ var HelpTopics = []helpTopic{ control some behavior. `), }, + { + name: "search", + short: "Search syntax for gh commands", + long: heredoc.Docf(` + Excluding search results that match a qualifier + + In a browser, the GitHub search syntax supports excluding results that match a search qualifier + by prefixing the qualifier with a hyphen. For example, to search for issues that + do not have the label "bug", you would use %[1]s-label:bug%[1]s as a search qualifier. + + %[1]sgh%[1]s supports this syntax in %[1]sgh search%[1]s as well, but it requires extra + syntax to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen. + + On Unix-like systems, you can use the %[1]s--%[1]s argument to indicate that + the arguments that follow are not a flag, but rather a query string. For example: + + $ gh search issues -- "my-search-query -label:bug" + + On PowerShell, you must use both the %[1]s--%[2]s%[1]s argument and the %[1]s--%[1]s argument to + produce the same effect. For example: + + $ gh --%[2]s search issues -- "my search query -label:bug" + + See the following for more information: + - GitHub search syntax: + - The PowerShell stop parse flag %[1]s--%[2]s%[1]s: + - The Unix-like %[1]s--%[1]s argument: + `, "`", "%"), + }, } func NewCmdHelpTopic(ios *iostreams.IOStreams, ht helpTopic) *cobra.Command { From dd0a0b3045fde60f8fd2bec7c0b1435173b80fa1 Mon Sep 17 00:00:00 2001 From: Sukh Date: Fri, 25 Jul 2025 19:49:59 -0400 Subject: [PATCH 04/13] docs(search): add reference to `gh help search` --- pkg/cmd/search/code/code.go | 3 +-- pkg/cmd/search/commits/commits.go | 7 +++---- pkg/cmd/search/issues/issues.go | 7 +++---- pkg/cmd/search/prs/prs.go | 7 +++---- pkg/cmd/search/repos/repos.go | 7 +++---- 5 files changed, 13 insertions(+), 18 deletions(-) diff --git a/pkg/cmd/search/code/code.go b/pkg/cmd/search/code/code.go index 3a439e5cd..5e80c1017 100644 --- a/pkg/cmd/search/code/code.go +++ b/pkg/cmd/search/code/code.go @@ -47,8 +47,7 @@ func NewCmdCode(f *cmdutil.Factory, runF func(*CodeOptions) error) *cobra.Comman The results might not match what is seen on %[1]sgithub.com%[1]s, and new features like regex search are not yet available via the GitHub API. - Note: When using GitHub search syntax to exclude results (e.g. '-language:xml'), you must use - a '--' delimiter before the search query to separate it from command flags. + For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. `, "`"), Example: heredoc.Doc(` # Search code matching "react" and "lifecycle" diff --git a/pkg/cmd/search/commits/commits.go b/pkg/cmd/search/commits/commits.go index 161ecc6a9..ed5d1f758 100644 --- a/pkg/cmd/search/commits/commits.go +++ b/pkg/cmd/search/commits/commits.go @@ -37,7 +37,7 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra. cmd := &cobra.Command{ Use: "commits []", Short: "Search for commits", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Search for commits on GitHub. The command supports constructing queries using the GitHub search syntax, @@ -46,9 +46,8 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra. GitHub search syntax is documented at: - Note: When using GitHub search syntax to exclude results (e.g. '-user:monalisa'), you must use - a '--' delimiter before the search query to separate it from command flags. - `), + For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + `, "`"), Example: heredoc.Doc(` # Search commits matching set of keywords "readme" and "typo" $ gh search commits readme typo diff --git a/pkg/cmd/search/issues/issues.go b/pkg/cmd/search/issues/issues.go index af6e9d64c..0edca4b31 100644 --- a/pkg/cmd/search/issues/issues.go +++ b/pkg/cmd/search/issues/issues.go @@ -26,7 +26,7 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c cmd := &cobra.Command{ Use: "issues []", Short: "Search for issues", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Search for issues on GitHub. The command supports constructing queries using the GitHub search syntax, @@ -35,9 +35,8 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c GitHub search syntax is documented at: - Note: When using GitHub search syntax to exclude results (e.g. '-label:bug'), you must use - a '--' delimiter before the search query to separate it from command flags. - `), + For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + `, "`"), Example: heredoc.Doc(` # Search issues matching set of keywords "readme" and "typo" $ gh search issues readme typo diff --git a/pkg/cmd/search/prs/prs.go b/pkg/cmd/search/prs/prs.go index b268ea3e5..39203f5fb 100644 --- a/pkg/cmd/search/prs/prs.go +++ b/pkg/cmd/search/prs/prs.go @@ -28,7 +28,7 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr cmd := &cobra.Command{ Use: "prs []", Short: "Search for pull requests", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Search for pull requests on GitHub. The command supports constructing queries using the GitHub search syntax, @@ -37,9 +37,8 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr GitHub search syntax is documented at: - Note: When using GitHub search syntax to exclude results (e.g. '-label:bug'), you must use - a '--' delimiter before the search query to separate it from command flags. - `), + For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + `, "`"), Example: heredoc.Doc(` # Search pull requests matching set of keywords "fix" and "bug" $ gh search prs fix bug diff --git a/pkg/cmd/search/repos/repos.go b/pkg/cmd/search/repos/repos.go index 733d7b7c4..a7116dd58 100644 --- a/pkg/cmd/search/repos/repos.go +++ b/pkg/cmd/search/repos/repos.go @@ -38,7 +38,7 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm cmd := &cobra.Command{ Use: "repos []", Short: "Search for repositories", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Search for repositories on GitHub. The command supports constructing queries using the GitHub search syntax, @@ -47,9 +47,8 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm GitHub search syntax is documented at: - Note: When using GitHub search syntax to exclude results (e.g. '-topic:linux'), you must use - a '--' delimiter before the search query to separate it from command flags. - `), + For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + `, "`"), Example: heredoc.Doc(` # Search repositories matching set of keywords "cli" and "shell" $ gh search repos cli shell From 73f6acc709e18d823fcb91df73de3932e75792f7 Mon Sep 17 00:00:00 2001 From: Sukh Date: Fri, 25 Jul 2025 19:56:39 -0400 Subject: [PATCH 05/13] docs(help): rename `search-syntax` help topic --- pkg/cmd/root/help_topic.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 6ea626e06..322bc4f77 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -305,7 +305,7 @@ var HelpTopics = []helpTopic{ `), }, { - name: "search", + name: "search-syntax", short: "Search syntax for gh commands", long: heredoc.Docf(` Excluding search results that match a qualifier From 6e400eb4a19e77f9d810ca73f679cac37c56df36 Mon Sep 17 00:00:00 2001 From: Sukh Date: Sat, 2 Aug 2025 03:01:40 -0400 Subject: [PATCH 06/13] docs(search): move search syntax note to `gh search --help` --- pkg/cmd/root/help_topic.go | 29 ----------------------------- pkg/cmd/search/code/code.go | 2 +- pkg/cmd/search/commits/commits.go | 2 +- pkg/cmd/search/issues/issues.go | 2 +- pkg/cmd/search/prs/prs.go | 2 +- pkg/cmd/search/repos/repos.go | 2 +- pkg/cmd/search/search.go | 29 ++++++++++++++++++++++++++++- 7 files changed, 33 insertions(+), 35 deletions(-) diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 322bc4f77..a375d9e20 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -304,35 +304,6 @@ var HelpTopics = []helpTopic{ control some behavior. `), }, - { - name: "search-syntax", - short: "Search syntax for gh commands", - long: heredoc.Docf(` - Excluding search results that match a qualifier - - In a browser, the GitHub search syntax supports excluding results that match a search qualifier - by prefixing the qualifier with a hyphen. For example, to search for issues that - do not have the label "bug", you would use %[1]s-label:bug%[1]s as a search qualifier. - - %[1]sgh%[1]s supports this syntax in %[1]sgh search%[1]s as well, but it requires extra - syntax to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen. - - On Unix-like systems, you can use the %[1]s--%[1]s argument to indicate that - the arguments that follow are not a flag, but rather a query string. For example: - - $ gh search issues -- "my-search-query -label:bug" - - On PowerShell, you must use both the %[1]s--%[2]s%[1]s argument and the %[1]s--%[1]s argument to - produce the same effect. For example: - - $ gh --%[2]s search issues -- "my search query -label:bug" - - See the following for more information: - - GitHub search syntax: - - The PowerShell stop parse flag %[1]s--%[2]s%[1]s: - - The Unix-like %[1]s--%[1]s argument: - `, "`", "%"), - }, } func NewCmdHelpTopic(ios *iostreams.IOStreams, ht helpTopic) *cobra.Command { diff --git a/pkg/cmd/search/code/code.go b/pkg/cmd/search/code/code.go index 5e80c1017..7ef2a4193 100644 --- a/pkg/cmd/search/code/code.go +++ b/pkg/cmd/search/code/code.go @@ -47,7 +47,7 @@ func NewCmdCode(f *cmdutil.Factory, runF func(*CodeOptions) error) *cobra.Comman The results might not match what is seen on %[1]sgithub.com%[1]s, and new features like regex search are not yet available via the GitHub API. - For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s. `, "`"), Example: heredoc.Doc(` # Search code matching "react" and "lifecycle" diff --git a/pkg/cmd/search/commits/commits.go b/pkg/cmd/search/commits/commits.go index ed5d1f758..939109b65 100644 --- a/pkg/cmd/search/commits/commits.go +++ b/pkg/cmd/search/commits/commits.go @@ -46,7 +46,7 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra. GitHub search syntax is documented at: - For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s. `, "`"), Example: heredoc.Doc(` # Search commits matching set of keywords "readme" and "typo" diff --git a/pkg/cmd/search/issues/issues.go b/pkg/cmd/search/issues/issues.go index 0edca4b31..1d6ec6428 100644 --- a/pkg/cmd/search/issues/issues.go +++ b/pkg/cmd/search/issues/issues.go @@ -35,7 +35,7 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c GitHub search syntax is documented at: - For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s. `, "`"), Example: heredoc.Doc(` # Search issues matching set of keywords "readme" and "typo" diff --git a/pkg/cmd/search/prs/prs.go b/pkg/cmd/search/prs/prs.go index 39203f5fb..98ab730b5 100644 --- a/pkg/cmd/search/prs/prs.go +++ b/pkg/cmd/search/prs/prs.go @@ -37,7 +37,7 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr GitHub search syntax is documented at: - For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s. `, "`"), Example: heredoc.Doc(` # Search pull requests matching set of keywords "fix" and "bug" diff --git a/pkg/cmd/search/repos/repos.go b/pkg/cmd/search/repos/repos.go index a7116dd58..0a4275a87 100644 --- a/pkg/cmd/search/repos/repos.go +++ b/pkg/cmd/search/repos/repos.go @@ -47,7 +47,7 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm GitHub search syntax is documented at: - For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s. `, "`"), Example: heredoc.Doc(` # Search repositories matching set of keywords "cli" and "shell" diff --git a/pkg/cmd/search/search.go b/pkg/cmd/search/search.go index e8714065b..e79e1ec4c 100644 --- a/pkg/cmd/search/search.go +++ b/pkg/cmd/search/search.go @@ -3,6 +3,7 @@ package search import ( "github.com/cli/cli/v2/pkg/cmdutil" "github.com/spf13/cobra" + "github.com/MakeNowJust/heredoc" searchCodeCmd "github.com/cli/cli/v2/pkg/cmd/search/code" searchCommitsCmd "github.com/cli/cli/v2/pkg/cmd/search/commits" @@ -15,7 +16,33 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "search ", Short: "Search for repositories, issues, and pull requests", - Long: "Search across all of GitHub.", + Long: heredoc.Docf(` + Search across all of GitHub. + + Excluding search results that match a qualifier + + In a browser, the GitHub search syntax supports excluding results that match a search qualifier + by prefixing the qualifier with a hyphen. For example, to search for issues that + do not have the label "bug", you would use %[1]s-label:bug%[1]s as a search qualifier. + + %[1]sgh%[1]s supports this syntax in %[1]sgh search%[1]s as well, but it requires extra + syntax to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen. + + On Unix-like systems, you can use the %[1]s--%[1]s argument to indicate that + the arguments that follow are not a flag, but rather a query string. For example: + + $ gh search issues -- "my-search-query -label:bug" + + On PowerShell, you must use both the %[1]s--%[2]s%[1]s argument and the %[1]s--%[1]s argument to + produce the same effect. For example: + + $ gh --%[2]s search issues -- "my search query -label:bug" + + See the following for more information: + - GitHub search syntax: + - The PowerShell stop parse flag %[1]s--%[2]s%[1]s: + - The Unix-like %[1]s--%[1]s argument: + `, "`", "%"), } cmd.AddCommand(searchCodeCmd.NewCmdCode(f, nil)) From 701b3d59f62db2a2f55f6a571c9649e138c77ce4 Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Tue, 5 Aug 2025 16:59:53 -0600 Subject: [PATCH 07/13] Update issue triage guidelines and label usage Clarifies the triage process for bugs, enhancements, and docs issues, including the responsibilities of the first responder (FR). Expands and reorganizes label definitions, adds new labels for investigation and team triage, and updates the pull request assignment process to be load balanced. Improves instructions for engaging with issues and managing labels. --- docs/triage.md | 50 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 37 insertions(+), 13 deletions(-) diff --git a/docs/triage.md b/docs/triage.md index 7f8bbbd7b..4f055e76f 100644 --- a/docs/triage.md +++ b/docs/triage.md @@ -6,10 +6,12 @@ As we get more issues and pull requests opened on the GitHub CLI, we've decided Review and label [open issues missing either the `enhancement`, `bug`, or `docs` label](https://github.com/cli/cli/issues?q=is%3Aopen+is%3Aissue+-label%3Abug%2Cenhancement%2Cdocs+) and the label(s) corresponding to the command space prefixed with `gh-`, such as `gh-pr` for the `gh pr` command set, or `gh-extension` for the `gh extension` command set. -Then, engage with the issue and community with the goal to remove the `needs-triage` label from the issue. The heuristics for triaging the different issue types are as follow: +The heuristics for triaging the different issue types are as follows: ### Bugs +For bugs, the FR should engage with the issue and community with the goal to remove the `needs-triage` label from the issue. + To be considered triaged, `bug` issues require the following: - A severity label `p1`, `p2`, and `p3` @@ -23,33 +25,55 @@ To be considered triaged, `bug` issues require the following: | `p2` | Affects more than a few users but doesn't prevent core functions | | `p3` | Affects a small number of users or is largely cosmetic | -### Enhancements +### Enhancements & Docs -To be considered triaged, `enhancement` issues require either +For `enhancement` issues, the FR's role is to prepare the issue for team review and triage. -- Clearly defined Acceptance Criteria as above -- The `needs-investigation` or `needs-design` label with a clearly defined set of open questions to be investigated. +When a new issue is opened, the FR **should**: -### Docs +- Acknowledge the issue +- Assign themselves to the issue +- Ensure there is enough information to understand the enhancement's scope and value +- Ask the user for more information about value and use-case, if necessary +- Leave the `needs-triage` label on the issue +- Add the `needs-user-input` and `needs-investigation` labels as needed -To be considered triaged, `docs` issues require clearly defined Acceptance Criteria, as defined above +When the FR has enough information to be triaged, they should: +- Remove the `needs-user-input` and `needs-investigation` labels +- Remove their assignment from the issue -## Additional triaging processes and labels +The FR should **avoid**: -Before removing the `needs-triage` label, consider adding any of the following labels below. +- Thoroughly investigating the enhancement's technical feasibility +- Prematurely accepting the enhancement request +- Removing the `needs-triage` label +- Labeling issues as `help wanted` + +## Additional triaging labels + +The FR can consider adding any of the following labels below. | Label | Description | | - | - | | `discuss` | Some issues require discussion with the internal team. Adding this label will automatically open up an internal discussion with the team to facilitate this discussion. | | `core` | Defines what we would like to do internally. We tend to lean towards `help wanted` by default, and adding `core` should be reserved for trickier issues or implementations we have strong opinions/preferences about. | -| `good first issue` | Used to denote when an issue may be a good candidate for a first-time contributor to the CLI. These are usually small and well defined issues. | -| `help wanted` | Defines what we feel the community could solve should they care to contribute, respectively. We tend to lean towards `help wanted` by default, and adding `core` should be reserved for trickier issues or implementations we have strong opinions/preferences about. | -| `invalid` | Added to spam and abusive issues. | | `needs-user-input` | After asking any contributors for more information, add this label so it is clear that the issue has been responded to and we are waiting on the user. | +| `needs-investigation` | Used when the issue requires further investigation before it can be reviewed and triaged. This is often used for issues that are not clearly bugs or enhancements, or when the FR needs to gather more information before proceeding. | +| `invalid` | Added to spam and abusive issues. | + +### Labels for team enhancement triaging + +The FR should **avoid** adding these labels outside of team enhancement triage. + +| Label | Description | +| - | - | +| `good first issue` | Used to denote when an issue may be a good candidate for a first-time contributor to the CLI. These are usually small and well defined issues. | +| `help wanted` | These issues are ready for community contribution. | +| `help wanted candidate` | Used to denote when an issue may be a good candidate for community contribution. Issues labelled this way are discussed internally and may be promoted to `help wanted`. | ## Expectations for community pull requests -All incoming pull requests are assigned to one of the engineers for review on a round-robin basis. +All incoming pull requests are assigned to one of the engineers for review on a load balanced basis. The person in a triage role for a week could take a glance at these pull requests, mostly to see whether the changeset is feasible and to allow the associated CI run for new contributors. From 7a60981ddece55f1631d302a814527676cd3571f Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Tue, 5 Aug 2025 17:18:56 -0600 Subject: [PATCH 08/13] Update docs/triage.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/triage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/triage.md b/docs/triage.md index 4f055e76f..ce97e77f8 100644 --- a/docs/triage.md +++ b/docs/triage.md @@ -25,7 +25,7 @@ To be considered triaged, `bug` issues require the following: | `p2` | Affects more than a few users but doesn't prevent core functions | | `p3` | Affects a small number of users or is largely cosmetic | -### Enhancements & Docs +### Enhancements and Docs For `enhancement` issues, the FR's role is to prepare the issue for team review and triage. From c69d11c3f4467011a263c3b434e79a20c49b41c4 Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Tue, 5 Aug 2025 17:19:05 -0600 Subject: [PATCH 09/13] Update docs/triage.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/triage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/triage.md b/docs/triage.md index ce97e77f8..ea119994c 100644 --- a/docs/triage.md +++ b/docs/triage.md @@ -73,7 +73,7 @@ The FR should **avoid** adding these labels outside of team enhancement triage. ## Expectations for community pull requests -All incoming pull requests are assigned to one of the engineers for review on a load balanced basis. +All incoming pull requests are assigned to one of the engineers for review on a load-balanced basis. The person in a triage role for a week could take a glance at these pull requests, mostly to see whether the changeset is feasible and to allow the associated CI run for new contributors. From 3d9bd69e11a5fc338ef9c84ff7caea3cf5193cb4 Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Wed, 6 Aug 2025 10:28:56 -0600 Subject: [PATCH 10/13] Update pkg/cmd/search/search.go --- pkg/cmd/search/search.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/cmd/search/search.go b/pkg/cmd/search/search.go index e79e1ec4c..551faf1f2 100644 --- a/pkg/cmd/search/search.go +++ b/pkg/cmd/search/search.go @@ -26,7 +26,7 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command { do not have the label "bug", you would use %[1]s-label:bug%[1]s as a search qualifier. %[1]sgh%[1]s supports this syntax in %[1]sgh search%[1]s as well, but it requires extra - syntax to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen. + command line arguments to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen. On Unix-like systems, you can use the %[1]s--%[1]s argument to indicate that the arguments that follow are not a flag, but rather a query string. For example: From 4dde0871bd6cd5207e54fa6c9183d5d52f53e81e Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Wed, 6 Aug 2025 10:32:46 -0600 Subject: [PATCH 11/13] Fix linter --- pkg/cmd/search/search.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pkg/cmd/search/search.go b/pkg/cmd/search/search.go index 551faf1f2..2f435f14d 100644 --- a/pkg/cmd/search/search.go +++ b/pkg/cmd/search/search.go @@ -1,9 +1,9 @@ package search import ( + "github.com/MakeNowJust/heredoc" "github.com/cli/cli/v2/pkg/cmdutil" "github.com/spf13/cobra" - "github.com/MakeNowJust/heredoc" searchCodeCmd "github.com/cli/cli/v2/pkg/cmd/search/code" searchCommitsCmd "github.com/cli/cli/v2/pkg/cmd/search/commits" @@ -16,7 +16,7 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "search ", Short: "Search for repositories, issues, and pull requests", - Long: heredoc.Docf(` + Long: heredoc.Docf(` Search across all of GitHub. Excluding search results that match a qualifier From f8de714c65cc6feebb608ab855b052cf4ef309da Mon Sep 17 00:00:00 2001 From: cli automation Date: Thu, 7 Aug 2025 03:32:50 +0000 Subject: [PATCH 12/13] Bump Go to 1.24.6 --- go.mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/go.mod b/go.mod index 7f0569303..d3125bcd2 100644 --- a/go.mod +++ b/go.mod @@ -2,7 +2,7 @@ module github.com/cli/cli/v2 go 1.24.0 -toolchain go1.24.5 +toolchain go1.24.6 require ( github.com/AlecAivazis/survey/v2 v2.3.7 From 762d1029fa1685e27187a7b4f66c37c2c18b2049 Mon Sep 17 00:00:00 2001 From: Andy Feller Date: Thu, 7 Aug 2025 09:24:17 -0400 Subject: [PATCH 13/13] Pushing empty commit to run CI